Merge branch 'crmne:main' into main

Author: bricolage

.overcommit.yml

@@ -18,11 +18,6 @@ PreCommit:
     exclude:
      - '**/db/structure.sql' # Ignore trailing whitespace in generated files
 
-  RakeTarget:
-    enabled: true
-    command: ['bundle', 'exec', 'rake']
-    targets: ['models:update', 'models:docs', 'aliases:generate']
-    on_warn: fail
 
   AppraisalUpdate:
     enabled: true

Gemfile

@@ -12,6 +12,7 @@ group :development do # rubocop:disable Metrics/BlockLength
   gem 'dotenv'
   gem 'ferrum'
   gem 'flay'
+  gem 'image_processing', '~> 1.2'
   gem 'irb'
   gem 'json-schema'
   gem 'nokogiri'

README.md

@@ -1,99 +1,114 @@
+<div align="center">
+
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="/docs/assets/images/logotype_dark.svg">
   <img src="/docs/assets/images/logotype.svg" alt="RubyLLM" height="120" width="250">
 </picture>
 
-**One *beautiful* Ruby API for GPT, Claude, Gemini, and more.** Easily build chatbots, AI agents, RAG applications, and content generators. Features chat (text, images, audio, PDFs), image generation, embeddings, tools (function calling), structured output, Rails integration, and streaming. Works with OpenAI, Anthropic, Google Gemini, AWS Bedrock, DeepSeek, Mistral, Ollama (local models), OpenRouter, Perplexity, GPUStack, and any OpenAI-compatible API.
+<strong>One *beautiful* Ruby API for GPT, Claude, Gemini, and more.</strong>
+
+Battle tested at [<picture><source media="(prefers-color-scheme: dark)" srcset="https://chatwithwork.com/logotype-dark.svg"><img src="https://chatwithwork.com/logotype.svg" alt="Chat with Work" height="30" align="absmiddle"></picture>](https://chatwithwork.com) — *Claude Code for your documents*
+
+[![Gem Version](https://badge.fury.io/rb/ruby_llm.svg?a=6)](https://badge.fury.io/rb/ruby_llm)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+[![Gem Downloads](https://img.shields.io/gem/dt/ruby_llm)](https://rubygems.org/gems/ruby_llm)
+[![codecov](https://codecov.io/gh/crmne/ruby_llm/branch/main/graph/badge.svg?a=1)](https://codecov.io/gh/crmne/ruby_llm)
 
-<div class="badge-container">
-  <a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg?a=5" 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>
+<a href="https://trendshift.io/repositories/13640" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13640" alt="crmne%2Fruby_llm | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
-Battle tested at [<picture><source media="(prefers-color-scheme: dark)" srcset="https://chatwithwork.com/logotype-dark.svg"><img src="https://chatwithwork.com/logotype.svg" alt="Chat with Work" height="30" align="absmiddle"></picture>](https://chatwithwork.com) — *Claude Code for your documents*
+---
+
+Build chatbots, AI agents, RAG applications. Works with OpenAI, Anthropic, Google, AWS, local models, and any OpenAI-compatible API.
 
-## The problem with AI libraries
+## Why RubyLLM?
 
-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.
+Every AI provider ships their own bloated client. Different APIs. Different response formats. Different conventions. It's exhausting.
 
-RubyLLM fixes all that. One beautiful API for everything. One consistent format. Minimal dependencies — just Faraday, Zeitwerk, and Marcel. Because working with AI should be a joy, not a chore.
+RubyLLM gives you one beautiful API for all of them. Same interface whether you're using GPT, Claude, or your local Ollama. Just three dependencies: Faraday, Zeitwerk, and Marcel. That's it.
 
-## What makes it great
+## Show me the code
 
 ```ruby
 # Just ask questions
 chat = RubyLLM.chat
 chat.ask "What's the best way to learn Ruby?"
+```
 
-# Analyze images, audio, documents, and text files
+```ruby
+# Analyze any file type
 chat.ask "What's in this image?", with: "ruby_conf.jpg"
 chat.ask "Describe this meeting", with: "meeting.wav"
 chat.ask "Summarize this document", with: "contract.pdf"
 chat.ask "Explain this code", with: "app.rb"
+```
 
-# Multiple files at once - types automatically detected
+```ruby
+# Multiple files at once
 chat.ask "Analyze these files", with: ["diagram.png", "report.pdf", "notes.txt"]
+```
 
-# Stream responses in real-time
-chat.ask "Tell me a story about a Ruby programmer" do |chunk|
+```ruby
+# Stream responses
+chat.ask "Tell me a story about Ruby" do |chunk|
   print chunk.content
 end
+```
 
+```ruby
 # Generate images
 RubyLLM.paint "a sunset over mountains in watercolor style"
+```
 
-# Create vector embeddings
+```ruby
+# Create embeddings
 RubyLLM.embed "Ruby is elegant and expressive"
+```
 
+```ruby
 # Let AI use your code
 class Weather < RubyLLM::Tool
-  description "Gets current weather for a location"
-  param :latitude, desc: "Latitude (e.g., 52.5200)"
-  param :longitude, desc: "Longitude (e.g., 13.4050)"
+  description "Get current weather"
+  param :latitude
+  param :longitude
 
   def execute(latitude:, longitude:)
     url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
-
-    response = Faraday.get(url)
-    data = JSON.parse(response.body)
-  rescue => e
-    { error: e.message }
+    JSON.parse(Faraday.get(url).body)
   end
 end
 
-chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
+chat.with_tool(Weather).ask "What's the weather in Berlin?"
+```
 
-# Get structured output with JSON schemas
+```ruby
+# Get structured output
 class ProductSchema < RubyLLM::Schema
-  string :name, description: "Product name"
-  number :price, description: "Price in USD"
-  array :features, description: "Key features" do
-    string description: "Feature description"
+  string :name
+  number :price
+  array :features do
+    string
   end
 end
 
-response = chat.with_schema(ProductSchema)
-               .ask "Analyze this product description", with: "product.txt"
-# response.content => { "name" => "...", "price" => 99.99, "features" => [...] }
+response = chat.with_schema(ProductSchema).ask "Analyze this product", with: "product.txt"
 ```
 
-## Core Capabilities
-
-*   💬 **Unified Chat:** Converse with models from OpenAI, Anthropic, Gemini, Bedrock, OpenRouter, DeepSeek, Perplexity, Mistral, Ollama, or any OpenAI-compatible API using `RubyLLM.chat`.
-*   👁️ **Vision:** Analyze images within chats.
-*   🔊 **Audio:** Transcribe and understand audio content.
-*   📄 **Document Analysis:** Extract information from PDFs, text files, CSV, JSON, XML, Markdown, and code files.
-*   🖼️ **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`.
-*   📋 **Structured Output:** Guarantee responses conform to JSON schemas with `RubyLLM::Schema`.
-*   🚂 **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.
-*   ⚡ **Async Support:** Built-in fiber-based concurrency for high-performance operations.
-*   🎯 **Smart Configuration:** Global and scoped configs with automatic retries and proxy support.
-*   📚 **Model Registry:** Access 500+ models with capability detection and pricing info.
+## Features
+
+* **Chat:** Conversational AI with `RubyLLM.chat`
+* **Vision:** Analyze images and screenshots
+* **Audio:** Transcribe and understand speech
+* **Documents:** Extract from PDFs, CSVs, JSON, any file type
+* **Image generation:** Create images with `RubyLLM.paint`
+* **Embeddings:** Vector search with `RubyLLM.embed`
+* **Tools:** Let AI call your Ruby methods
+* **Structured output:** JSON schemas that just work
+* **Streaming:** Real-time responses with blocks
+* **Rails:** ActiveRecord integration with `acts_as_chat`
+* **Async:** Fiber-based concurrency
+* **Model registry:** 500+ models with capability detection and pricing
+* **Providers:** OpenAI, Anthropic, Gemini, Bedrock, DeepSeek, Mistral, Ollama, OpenRouter, Perplexity, GPUStack, and any OpenAI-compatible API
 
 ## Installation
 
@@ -103,69 +118,36 @@ gem 'ruby_llm'
 ```
 Then `bundle install`.
 
-Configure your API keys (using environment variables is recommended):
+Configure your API keys:
 ```ruby
-# config/initializers/ruby_llm.rb or similar
+# config/initializers/ruby_llm.rb
 RubyLLM.configure do |config|
-  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', 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 ...
+  config.openai_api_key = ENV['OPENAI_API_KEY']
 end
 ```
-See the [Installation Guide](https://rubyllm.com/installation) for full details.
 
-## Rails Integration
-
-Add persistence to your chat models effortlessly:
+## Rails
 
 ```bash
-# Generate models and migrations
 rails generate ruby_llm:install
 ```
 
 ```ruby
-# Or add to existing models
 class Chat < ApplicationRecord
-  acts_as_chat # Automatically saves messages & tool calls
-end
-
-class Message < ApplicationRecord
-  acts_as_message
+  acts_as_chat
 end
 
-class ToolCall < ApplicationRecord
-  acts_as_tool_call
-end
-
-# Now chats persist automatically
-chat = Chat.create!(model_id: "gpt-4.1-nano")
-chat.ask("What's in this file?", with: "report.pdf")
+chat = Chat.create! model_id: "claude-sonnet-4"
+chat.ask "What's in this file?", with: "report.pdf"
 ```
 
-See the [Rails Integration Guide](https://rubyllm.com/guides/rails) for details.
-
-## Learn More
-
-Dive deeper with the official documentation:
+## 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)
+[rubyllm.com](https://rubyllm.com)
 
 ## Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on setup, testing, and contribution guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

bin/console

@@ -8,20 +8,21 @@ require 'dotenv/load'
 require 'irb'
 
 RubyLLM.configure do |config|
-  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
-  config.openai_api_base = ENV.fetch('OPENAI_API_BASE', 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)
-  config.perplexity_api_key = ENV.fetch('PERPLEXITY_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)
+  config.bedrock_secret_key = ENV.fetch('AWS_SECRET_ACCESS_KEY', nil)
   config.bedrock_session_token = ENV.fetch('AWS_SESSION_TOKEN', nil)
+  config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
+  config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)
   config.gpustack_api_base = ENV.fetch('GPUSTACK_API_BASE', nil)
   config.gpustack_api_key = ENV.fetch('GPUSTACK_API_KEY', nil)
+  config.mistral_api_key = ENV.fetch('MISTRAL_API_KEY', nil)
+  config.ollama_api_base = ENV.fetch('OLLAMA_API_BASE', nil)
+  config.openai_api_base = ENV.fetch('OPENAI_API_BASE', nil)
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+  config.openrouter_api_key = ENV.fetch('OPENROUTER_API_KEY', nil)
+  config.perplexity_api_key = ENV.fetch('PERPLEXITY_API_KEY', nil)
 end
 
 IRB.start(__FILE__)

docs/_getting_started/getting-started.md

@@ -5,6 +5,7 @@ nav_order: 1
 description: Start building AI apps in Ruby in 5 minutes. Chat, generate images, create embeddings - all with one gem.
 redirect_from:
   - /guides/getting-started
+  - /installation
 ---
 
 # {{ page.title }}