Add DB-backed model registry with ActiveRecord associations

Implements the new Model registry feature that replaces simple string fields
with proper ActiveRecord associations, enabling rich model metadata, provider
routing, and usage tracking.

Key features:
- Model associations with foreign keys for better data integrity
- Rich model metadata (context_window, capabilities, pricing, etc.)
- Provider-specific model routing
- Automatic model population from models.json during migration
- Backward compatibility through model_id= setter
- Support for assume_model_exists with dynamic model creation
- Context attribute for multi-tenant applications

Migration improvements:
- Fresh installs automatically get model registry
- Existing apps can migrate with rails generate ruby_llm:migrate_model_fields
- Legacy mode continues to work with deprecation warning
- Models table auto-populated from models.json

Rails integration updates:
- Context must be passed at Chat.create! for DB-backed registry
- Legacy mode retains with_context method
- Added documentation for context persistence considerations

Testing enhancements:
- Added tests for assume_model_exists with fictional models
- Database reload after test model creation
- Proper error handling for non-existent models
- Fixed generator specs for new migration structure

Author: crmne

docs/_advanced/rails.md

@@ -77,9 +77,10 @@ After running the generator:
 
 ```bash
 rails db:migrate
+rails ruby_llm:load_models  # Populates the models table from models.json
 ```
 
-You're ready to go! The generator handles all the setup complexity for you.
+You're ready to go! The generator handles all the setup complexity for you, including configuring the DB-backed model registry.
 
 #### Generator Options
 
@@ -89,8 +90,8 @@ The generator supports custom model names if needed:
 # Use custom model names
 rails generate ruby_llm:install --chat-model-name=Conversation --message-model-name=ChatMessage --tool-call-model-name=FunctionCall
 
-# Skip the Model registry (opt-out)
-rails generate ruby_llm:install --skip-model
+# Skip the Model registry (uses string fields instead)
+rails generate ruby_llm:install --skip-model-registry
 ```
 
 This is useful if you already have models with these names or prefer different naming conventions.
@@ -236,7 +237,6 @@ class Chat < ApplicationRecord
 
   # --- Add your standard Rails model logic below ---
   belongs_to :user, optional: true # Example
-  validates :model_id, presence: true # Example
 end
 
 # app/models/message.rb
@@ -270,28 +270,105 @@ class Model < ApplicationRecord
 end
 ```
 
-### Setup RubyLLM.chat yourself
+### Using Provider Overrides
 
-In some scenarios, you need to tap into the power and arguments of `RubyLLM.chat`. For example, if want to use model aliases with alternate providers. Here is a working example:
+With the DB-backed model registry (v1.7.0+), you can specify alternate providers:
 
 ```ruby
- class Chat < ApplicationRecord
-    acts_as_chat
+# Use a model through a different provider
+chat = Chat.create!(
+  model: 'claude-3-5-sonnet',
+  provider: 'bedrock'  # Use AWS Bedrock instead of Anthropic
+)
+
+# The model registry handles the routing automatically
+chat.ask("Hello!")
+```
+
+### Custom Contexts and Dynamic Models
+{: .d-inline-block }
+
+Available in v1.7.0+
+{: .label .label-green }
+
+#### Using Custom Contexts
+
+For multi-tenant applications or when you need different API keys per chat:
+
+**With DB-backed model registry (default in v1.7.0+):**
+
+```ruby
+# Create a custom context
+custom_context = RubyLLM.context do |config|
+  config.openai_api_key = 'sk-customer-specific-key'
+end
+
+# Pass context when creating the chat
+chat = Chat.create!(
+  model: 'gpt-4',
+  context: custom_context
+)
+```
+
+**Legacy mode (when using `--skip-model-registry`):**
+
+```ruby
+# In legacy mode, you can set context after creation
+chat = Chat.create!(model_id: 'gpt-4')
+chat.with_context(custom_context)  # This method only exists in legacy mode
+```
+
+> The `context` is NOT persisted to the database. You must set it again when reloading chats:
+{: .warning }
 
-    validates :model_id, presence: true
-    validates :provider, presence: true
+```ruby
+# Later, in a different request or after restart
+chat = Chat.find(chat_id)
+chat.context = custom_context  # Must set this!
+chat.ask("Continue our conversation")
+```
+
+For multi-tenant apps, consider using an `after_find` callback:
+
+```ruby
+class Chat < ApplicationRecord
+  acts_as_chat
+  belongs_to :tenant
 
-    after_initialize :set_chat
+  after_find :set_tenant_context
 
-    def set_chat
-      @chat = RubyLLM.chat(model: model_id, provider:)
+  private
+
+  def set_tenant_context
+    self.context = RubyLLM.context do |config|
+      config.openai_api_key = tenant.openai_api_key
     end
   end
+end
+```
+
+#### Dynamic Model Creation
+
+When using models not in the registry (e.g., new OpenRouter models):
 
-  # Then in your controller or background job:
-  Chat.new(model_id: 'alias', provider: 'provider_name')
+```ruby
+# Create chat with a dynamic model
+chat = Chat.create!(
+  model: 'experimental-llm-v2',
+  provider: 'openrouter',
+  assume_model_exists: true  # Creates Model record automatically
+)
 ```
 
+> Like `context`, `assume_model_exists` is NOT persisted. Set it when needed for model changes:
+{: .note }
+
+```ruby
+# When switching to another dynamic model later
+chat = Chat.find(chat_id)
+chat.assume_model_exists = true
+chat.with_model('another-experimental-model', provider: 'openrouter')
+```
 
 ## Basic Usage
 
@@ -333,24 +410,25 @@ Available in v1.7.0+
 When using the Model registry (created by default by the generator), your chats and messages get associations to model records:
 
 ```ruby
-chat = Chat.create! model_id: 'gpt-4.1-nano'
-chat.model # => #<Model model_id: "gpt-4.1-nano", provider: "openai">
-chat.model.context_window # => 1047576
-chat.model.supports? 'structured_output' # => true
+# String automatically resolves to Model record
+chat = Chat.create!(model: 'gpt-4')
+chat.model # => #<Model model_id: "gpt-4o", provider: "openai">
+chat.model.name # => "GPT-4"
+chat.model.context_window # => 128000
+chat.model.supports_vision # => true
 
-# Populate your database with all available models
-Model.refresh!
+# Populate/refresh models from models.json
+rails ruby_llm:load_models
 
 # Query based on model attributes
 Chat.joins(:model).where(models: { provider: 'anthropic' })
 Model.left_joins(:chats).group(:id).order('COUNT(chats.id) DESC')
 
-# Extend with custom attributes via migration
-Model.where('monthly_limit > ?', 1000)
+# Find models with specific capabilities
+Model.where(supports_functions: true)
+Model.where(supports_vision: true)
 ```
 
-The registry automatically falls back to JSON if the database is unavailable, ensuring resilience.
-
 ### System Instructions
 
 Instructions (system prompts) set via `with_instructions` are also automatically persisted as `Message` records with the `system` role:

docs/_advanced/upgrading-to-1.7.md

@@ -0,0 +1,105 @@
+---
+layout: default
+title: Upgrading to 1.7
+nav_order: 6
+description: Upgrade to the DB-backed model registry for better data integrity and rich model metadata.
+---
+
+# {{ page.title }}
+{: .no_toc }
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## What's New in 1.7
+
+Among other features, the DB-backed model registry replaces simple string fields with proper ActiveRecord associations.
+
+### Available with DB-backed Model Registry (1.7+)
+
+**Rich model metadata**
+```ruby
+chat.model.name              # => "GPT-4"
+chat.model.context_window    # => 128000
+chat.model.supports_vision   # => true
+chat.model.input_token_cost  # => 2.50
+```
+
+**Provider routing**
+```ruby
+Chat.create!(model: "claude-3-5-sonnet", provider: "bedrock")
+```
+
+**Model associations and queries**
+```ruby
+Chat.joins(:model).where(models: { provider: 'anthropic' })
+Model.select { |m| m.supports_functions? }  # Use delegated methods
+```
+
+**Model alias resolution**
+```ruby
+Chat.create!(model: "gpt-4.1-nano", provider: "openrouter")  # Resolves to openai/gpt-4.1-nano automatically
+```
+
+**Usage tracking**
+```ruby
+Model.joins(:chats).group(:id).order('COUNT(chats.id) DESC')
+```
+
+### Available without Model Registry (<1.7 or legacy mode)
+
+**Basic functionality** - All core RubyLLM features work
+```ruby
+chat.ask("Hello!")  # Works fine
+chat.model_id  # => "gpt-4" (string only, no metadata)
+```
+
+**Limited to:**
+- String-based model IDs only
+- Default provider routing
+
+## Upgrading from 1.6
+
+### Your App Continues Working
+
+Without any changes, your 1.6 app continues to work with string fields. You'll see a deprecation warning on Rails boot.
+
+### Migrate to Model Registry (Recommended)
+
+```bash
+rails generate ruby_llm:install
+rails generate ruby_llm:migrate_model_fields
+rails db:migrate
+```
+
+Then enable it in your initializer:
+
+```ruby
+# config/initializers/ruby_llm.rb
+RubyLLM.configure do |config|
+  config.model_registry_class = "Model"
+end
+```
+
+That's it! The migration:
+- Creates the models table
+- Loads all models from models.json automatically
+- Migrates your existing data to use foreign keys
+- Preserves everything (renames old columns to `model_id_string`)
+
+## New Applications
+
+Fresh installs get the model registry automatically:
+
+```bash
+rails generate ruby_llm:install
+rails db:migrate
+```

docs/_getting_started/getting-started.md

@@ -35,17 +35,15 @@ After reading this guide, you will know:
 Add RubyLLM to your Gemfile:
 
 ```ruby
-gem 'ruby_llm'
+bundle add ruby_llm
 ```
 
-Then run `bundle install`.
-
 ### Rails Quick Setup
 
 For Rails applications, you can use the generator to set up database-backed conversations:
 
 ```bash
-$ rails generate ruby_llm:install
+rails generate ruby_llm:install
 ```
 
 This creates Chat and Message models with ActiveRecord persistence. Your conversations will be automatically saved to the database. See the [Rails Integration Guide]({% link _advanced/rails.md %}) for full details.

gemfiles/rails_7.1.gemfile.lock

@@ -214,7 +214,7 @@ GEM
     mutex_m (0.3.0)
     net-http (0.6.0)
       uri
-    net-imap (0.5.9)
+    net-imap (0.5.10)
       date
       net-protocol
     net-pop (0.1.2)

gemfiles/rails_7.2.gemfile.lock

@@ -207,7 +207,7 @@ GEM
     multipart-post (2.4.1)
     net-http (0.6.0)
       uri
-    net-imap (0.5.9)
+    net-imap (0.5.10)
       date
       net-protocol
     net-pop (0.1.2)

gemfiles/rails_8.0.gemfile.lock

@@ -207,7 +207,7 @@ GEM
     multipart-post (2.4.1)
     net-http (0.6.0)
       uri
-    net-imap (0.5.9)
+    net-imap (0.5.10)
       date
       net-protocol
     net-pop (0.1.2)