RubyLLM: A Unified Ruby Framework for All Major AI Providers

RubyLLM provides a single, elegant interface to interact with the most powerful AI models available today. Whether you are building sophisticated AI agents, RAG (Retrieval-Augmented Generation) systems, autonomous chatbots, or automated content pipelines, RubyLLM streamlines the entire workflow.

"Stop worrying about provider-specific SDKs. Use one beautiful framework for everything."

---

🚀 Quick Start: AI in Minutes

The core philosophy of RubyLLM is consistency. The interface remains identical regardless of whether you are calling GPT-4, Claude 3.5, or a local Ollama instance.

Basic Interactions

# Simple text query
chat.ask "What's the best way to learn Ruby?"

# Analyzing a specific file
chat.ask "What's happening in this video?", with: "video.mp4"

# Code analysis
chat.ask "Explain this code", with: "app.rb"

# Multi-modal analysis (Mixed file types)
chat.ask "Analyze these files", with: ["diagram.png", "report.pdf", "notes.txt"]

# Real-time streaming responses
chat.ask("Tell me a long story") { |chunk| print chunk }

Specialized AI Capabilities

RubyLLM goes beyond simple chat. It handles media, embeddings, and safety:

• Image Generation: RubyLLM.paint "a sunset over mountains in watercolor style"
• Vector Embeddings: RubyLLM.embed "Ruby is elegant and expressive"
• Audio Transcription: RubyLLM.transcribe "meeting.wav"
• Content Safety: RubyLLM.moderate "Check if this text is safe"

---

🛠️ Advanced Tooling & Agents

RubyLLM allows the AI to interact with your own Ruby logic through Tools and Agents.

1. Defining Tools

You can turn any Ruby class into a tool the AI can execute.

class Weather < RubyLLM::Tool
  desc "Get current weather"
  def execute(latitude:, longitude:)
    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
    # Return JSON response from API
  end
end

2. Creating Agents

Agents combine a specific model, a set of instructions, and the tools they are allowed to use.

class WeatherAssistant < RubyLLM::Agent
  model "gpt-5-nano"
  instructions "Be concise and always use tools for weather."
  tools Weather
end

# The agent now knows how to use the Weather tool to answer this:
WeatherAssistant.ask "What's the weather in Berlin?"

3. Structured Output

Ensure the AI returns data in a format your application can actually use via RubyLLM::Schema.

class ProductSchema < RubyLLM::Schema
  string :name
  number :price
  array :features do
    string
  end
end

response = chat.ask "Analyze this product", with: "product.txt", schema: ProductSchema

---

📊 Feature Matrix

Feature	Method/Class	Description
Conversational AI	RubyLLM.chat	Standard LLM interactions
Computer Vision	chat.ask	Analyze images and video files
Speech-to-Text	RubyLLM.transcribe	Convert audio to text
Doc Extraction	chat.ask	Parse PDFs, CSVs, JSON, etc.
Image Creation	RubyLLM.paint	Text-to-image generation
Vectorization	RubyLLM.embed	Generate embeddings for RAG
Safety	RubyLLM.moderate	Content moderation filters
Custom Logic	RubyLLM::Tool	Let AI call your Ruby methods
Persona Mgmt	RubyLLM::Agent	Reusable assistants with instructions
Type Safety	RubyLLM::Schema	Guaranteed JSON structured output
Performance	Fiber	Async, non-blocking concurrency

---

🌐 Ecosystem & Integration

Supported Providers

No more switching gems for different providers. RubyLLM supports:

• Cloud Giants: OpenAI, Anthropic, Google Gemini, VertexAI, AWS Bedrock.
• Open Source/Local: Ollama, DeepSeek, Mistral, GPUStack.
• Aggregators: OpenRouter, Perplexity, xAI.
• Compatibility: Any OpenAI-compatible API.

Model Intelligence

The framework includes a Model Registry featuring over 800 models. It automatically handles:

1. Capability Detection: Knows if a model supports vision or tools.
2. Pricing Logic: Calculates costs based on token usage. $\text{Total Cost} = (\text{Input Tokens} \times \text{Price}_{\text{in}}) + (\text{Output Tokens} \times \text{Price}_{\text{out}})$
3. Extended Thinking: Ability to view, control, and persist the "deliberation" process of reasoning models.

Architecture Flow

---

📦 Installation & Setup

Basic Setup

• Add gem 'ruby_llm' to your Gemfile.
• Run bundle install.
• Configure your credentials:

# config/initializers/ruby_llm.rb
RubyLLM.configure do
  openai_api_key = ENV['OPENAI_API_KEY']
end

Rails Integration

RubyLLM offers deep integration for Rails apps to persist chat histories.

# Setup the integration
bin/rails generate ruby_llm:install
bin/rails db:migrate
bin/rails ruby_llm:load_models # Updates the model registry (v1.13+)

# Optional: Add a pre-built Chat UI
bin/rails generate ruby_llm:chat_ui

Usage in Models:

class Chat < ApplicationRecord
  acts_as_chat
end

# Now you can ask questions directly through the model
chat = Chat.create
chat.ask "What's in this file?", with: "report.pdf"

Visit http://localhost:3000/chats to see your ready-to-use interface!