Merge branch 'main' into CustomParamsSchema

Author: crmne

.github/workflows/cicd.yml

@@ -50,6 +50,8 @@ jobs:
 
     - name: Run tests
       run: bundle exec rspec
+      env:
+        OLLAMA_API_BASE: http://localhost:11434/v1 # dummy
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v5
@@ -118,8 +120,8 @@ jobs:
     - name: Test with real APIs before publishing
       if: steps.check_version.outputs.version_changed == 'true'
       run: |
-        echo "Removing all VCR cassettes to test against real APIs..."
-        rm -rf spec/fixtures/vcr_cassettes
+        echo "Removing VCR cassettes except Ollama ones..."
+        find spec/fixtures/vcr_cassettes -type f ! -name '*ollama*' -delete
 
         echo "Running tests with real API calls..."
         env -u CI bundle exec rspec --fail-fast
@@ -128,6 +130,8 @@ jobs:
         ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
         GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
         DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+        OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+        OLLAMA_API_BASE: http://localhost:11434/v1 # dummy
         AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
 

.overcommit.yml

@@ -18,6 +18,11 @@ PreCommit:
     exclude:
      - '**/db/structure.sql' # Ignore trailing whitespace in generated files
 
+  RakeTarget:
+    enabled: true
+    targets: ['models:update', 'models:docs']
+    on_warn: fail
+
 PostCheckout:
   ALL: # Special hook name that customizes all hooks of this type
     quiet: true # Change all post-checkout hooks to only display output on failure

README.md

@@ -1,44 +1,44 @@
 <img src="/docs/assets/images/logotype.svg" alt="RubyLLM" height="120" width="250">
 
-A delightful Ruby way to work with AI. No configuration madness, no complex callbacks, no handler hell – just beautiful, expressive Ruby code.
-
-<div style="display: flex; align-items: center; flex-wrap: wrap; margin-bottom: 1em">
-  <img src="https://upload.wikimedia.org/wikipedia/commons/4/4d/OpenAI_Logo.svg" alt="OpenAI" height="40" width="120">
-  &nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Anthropic_logo.svg" alt="Anthropic" height="40" width="120">
-  &nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/8/8a/Google_Gemini_logo.svg" alt="Google" height="40" width="120">
-  &nbsp;&nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-color.svg" alt="Bedrock" height="40">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-text.svg" alt="Bedrock" height="40" width="120">
-  &nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/e/ec/DeepSeek_logo.svg" alt="DeepSeek" height="40" width="120">
+**A delightful Ruby way to work with AI.** RubyLLM provides **one** beautiful, Ruby-like interface to interact with modern AI models. Chat, generate images, create embeddings, and use tools – all with clean, expressive code that feels like Ruby, not like patching together multiple services.
+
+<div class="provider-icons">
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" alt="Anthropic" class="logo-small">
+  &nbsp;
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-color.svg" alt="Bedrock" class="logo-medium">
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-text.svg" alt="Bedrock" class="logo-small">
+  &nbsp;
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-color.svg" alt="DeepSeek" class="logo-medium">
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-text.svg" alt="DeepSeek" class="logo-small">
+  &nbsp;
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-brand-color.svg" alt="Gemini" class="logo-large">
+  &nbsp;
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama.svg" alt="Ollama" class="logo-medium">
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama-text.svg" alt="Ollama" class="logo-medium">
+  &nbsp;
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" alt="OpenAI" class="logo-medium">
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai-text.svg" alt="OpenAI" class="logo-medium">
+  &nbsp;
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter.svg" alt="OpenRouter" class="logo-medium">
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter-text.svg" alt="OpenRouter" class="logo-small">
+  &nbsp;
 </div>
 
-<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>
+<div class="badge-container">
+  <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>
+</div>
 
-🤺 Battle tested at [💬  Chat with Work](https://chatwithwork.com)
+🤺 Battle tested at [💬 Chat with Work](https://chatwithwork.com)
 
 ## The problem with AI libraries
 
 Every AI provider comes with its own client library, its own response format, its own conventions for streaming, and its own way of handling errors. Want to use multiple providers? Prepare to juggle incompatible APIs and bloated dependencies.
 
 RubyLLM fixes all that. One beautiful API for everything. One consistent format. Minimal dependencies — just Faraday and Zeitwerk. Because working with AI should be a joy, not a chore.
 
-## Features
-
-- 💬 **Chat** with OpenAI, Anthropic, Gemini, AWS Bedrock Anthropic, and DeepSeek models
-- 👁️ **Vision and Audio** understanding
-- 📄 **PDF Analysis** for analyzing documents
-- 🖼️ **Image generation** with DALL-E and other providers
-- 📊 **Embeddings** for vector search and semantic analysis
-- 🔧 **Tools** that let AI use your Ruby code
-- 🚂 **Rails integration** to persist chats and messages with ActiveRecord
-- 🌊 **Streaming** responses with proper Ruby patterns
-
 ## What makes it great
 
 ```ruby
@@ -85,142 +85,89 @@ end
 chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
 ```
 
+## Core Capabilities
+
+*   💬 **Unified Chat:** Converse with models from OpenAI, Anthropic, Gemini, Bedrock, OpenRouter, DeepSeek, Ollama, or any OpenAI-compatible API using `RubyLLM.chat`.
+*   👁️ **Vision:** Analyze images within chats.
+*   🔊 **Audio:** Transcribe and understand audio content.
+*   📄 **PDF Analysis:** Extract information and summarize PDF documents.
+*   🖼️ **Image Generation:** Create images with `RubyLLM.paint`.
+*   📊 **Embeddings:** Generate text embeddings for vector search with `RubyLLM.embed`.
+*   🔧 **Tools (Function Calling):** Let AI models call your Ruby code using `RubyLLM::Tool`.
+*   🚂 **Rails Integration:** Easily persist chats, messages, and tool calls using `acts_as_chat` and `acts_as_message`.
+*   🌊 **Streaming:** Process responses in real-time with idiomatic Ruby blocks.
+
 ## Installation
 
+Add to your Gemfile:
 ```ruby
-# In your Gemfile
 gem 'ruby_llm'
-
-# Then run
-bundle install
-
-# Or install it yourself
-gem install ruby_llm
 ```
+Then `bundle install`.
 
-Configure with your API keys:
-
+Configure your API keys (using environment variables is recommended):
 ```ruby
+# config/initializers/ruby_llm.rb or similar
 RubyLLM.configure do |config|
   config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
-  config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
-  config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)
-  config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
-
-  # Bedrock
-  config.bedrock_api_key = ENV.fetch('AWS_ACCESS_KEY_ID', nil)
-  config.bedrock_secret_key = ENV.fetch('AWS_SECRET_ACCESS_KEY', nil)
-  config.bedrock_region = ENV.fetch('AWS_REGION', nil)
-  config.bedrock_session_token = ENV.fetch('AWS_SESSION_TOKEN', nil)
+  # Add keys ONLY for providers you intend to use
+  # config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
+  # ... see Configuration guide for all options ...
 end
 ```
+See the [Installation Guide](https://rubyllm.com/installation) for full details.
 
-## Have great conversations
-
-```ruby
-# Start a chat with the default model (gpt-4.1-nano)
-chat = RubyLLM.chat
-
-# Or specify what you want
-chat = RubyLLM.chat(model: 'claude-3-7-sonnet-20250219')
-
-# Simple questions just work
-chat.ask "What's the difference between attr_reader and attr_accessor?"
-
-# Multi-turn conversations are seamless
-chat.ask "Could you give me an example?"
-
-# Stream responses in real-time
-chat.ask "Tell me a story about a Ruby programmer" do |chunk|
-  print chunk.content
-end
-
-# Set personality or behavior with instructions (aka system prompts)
-chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
-
-# Understand content in multiple forms
-chat.ask "Compare these diagrams", with: { image: ["diagram1.png", "diagram2.png"] }
-chat.ask "Summarize this document", with: { pdf: "contract.pdf" }
-chat.ask "What's being said?", with: { audio: "meeting.wav" }
-
-# Need a different model mid-conversation? No problem
-chat.with_model('gemini-2.0-flash').ask "What's your favorite algorithm?"
-```
+## Rails Integration
 
-## Rails integration that makes sense
+Add persistence to your chat models effortlessly:
 
 ```ruby
 # app/models/chat.rb
 class Chat < ApplicationRecord
-  acts_as_chat
-
-  # Works great with Turbo
-  broadcasts_to ->(chat) { "chat_#{chat.id}" }
+  acts_as_chat # Automatically saves messages & tool calls
+  # ... your other model logic ...
 end
 
 # app/models/message.rb
 class Message < ApplicationRecord
   acts_as_message
+  # ...
 end
 
-# app/models/tool_call.rb
+# app/models/tool_call.rb (if using tools)
 class ToolCall < ApplicationRecord
   acts_as_tool_call
+  # ...
 end
 
-# In a background job
-chat = Chat.create! model_id: "gpt-4.1-nano"
-
-# Set personality or behavior with instructions (aka system prompts) - they're persisted too!
-chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
-
-chat.ask("What's your favorite Ruby gem?") do |chunk|
-  Turbo::StreamsChannel.broadcast_append_to(
-    chat,
-    target: "response",
-    partial: "messages/chunk",
-    locals: { chunk: chunk }
-  )
-end
-
-# That's it - chat history is automatically saved
+# Now interacting with a Chat record persists the conversation:
+chat_record = Chat.create!(model_id: "gpt-4.1-nano")
+chat_record.ask("Explain Active Record callbacks.") # User & Assistant messages saved
 ```
-
-## Creating tools is a breeze
-
-```ruby
-class Search < RubyLLM::Tool
-  description "Searches a knowledge base"
-
-  param :query, desc: "The search query"
-  param :limit, type: :integer, desc: "Max results", required: false
-
-  def execute(query:, limit: 5)
-    # Your search logic here
-    Document.search(query).limit(limit).map(&:title)
-  end
-end
-
-# Let the AI use it
-chat.with_tool(Search).ask "Find documents about Ruby 3.3 features"
-```
-
-## Learn more
-
-Check out the guides at https://rubyllm.com for deeper dives into conversations with tools, streaming responses, embedding generations, and more.
+Check the [Rails Integration Guide](https://rubyllm.com/guides/rails) for more.
+
+## Learn More
+
+Dive deeper with the official documentation:
+
+-   [Installation](https://rubyllm.com/installation)
+-   [Configuration](https://rubyllm.com/configuration)
+-   **Guides:**
+    -   [Getting Started](https://rubyllm.com/guides/getting-started)
+    -   [Chatting with AI Models](https://rubyllm.com/guides/chat)
+    -   [Using Tools](https://rubyllm.com/guides/tools)
+    -   [Streaming Responses](https://rubyllm.com/guides/streaming)
+    -   [Rails Integration](https://rubyllm.com/guides/rails)
+    -   [Image Generation](https://rubyllm.com/guides/image-generation)
+    -   [Embeddings](https://rubyllm.com/guides/embeddings)
+    -   [Working with Models](https://rubyllm.com/guides/models)
+    -   [Error Handling](https://rubyllm.com/guides/error-handling)
+    -   [Available Models](https://rubyllm.com/guides/available-models)
 
 ## Contributing
 
-We welcome contributions to RubyLLM!
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on how to:
-- Run the test suite
-- Add new features
-- Update documentation
-- Re-record VCR cassettes when needed
-
-We appreciate your help making RubyLLM better!
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on setup, testing, and contribution guidelines.
 
 ## License
 
-Released under the MIT License.
+Released under the MIT License.

bin/console

@@ -12,6 +12,8 @@ RubyLLM.configure do |config|
   config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
   config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)
   config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
+  config.openrouter_api_key = ENV.fetch('OPENROUTER_API_KEY', nil)
+  config.ollama_api_base = ENV.fetch('OLLAMA_API_BASE', nil)
   config.bedrock_api_key = ENV.fetch('AWS_ACCESS_KEY_ID', nil)
   config.bedrock_secret_key = ENV.fetch('AWS_SECRET_ACCESS_KEY', nil)
   config.bedrock_region = ENV.fetch('AWS_REGION', nil)

docs/_sass/custom/custom.scss

@@ -0,0 +1,39 @@
+.logo-container {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 1em;
+}
+
+.provider-icons {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 1em;
+  margin-bottom: 1em;
+}
+
+.provider-logo {
+  display: flex;
+  align-items: center;
+  gap: 0.2em;
+}
+
+.logo-small {
+  height: 20px;
+}
+
+.logo-medium {
+  height: 30px;
+}
+
+.logo-large {
+  height: 50px;
+}
+
+.badge-container {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.2em;
+}