README

The Ruby AI framework

Build AI features the Ruby way: models, tools, agents, evaluations, and Rails conventions, designed together, with one consistent API.



ruby
chat = RubyLLM.chat
chat.ask "What's the best way to learn Ruby?"
chat.ask "What's in this image?", with: "ruby_conf.jpg"
chat.with_model("claude-sonnet-5").ask "Now say it as a haiku"

RubyLLM.paint("a sunset over mountains in watercolor").save("sunset.png")




Website · Getting Started · What's New in 2.1

Battle tested at  - Fully private work AI









https://github.com/user-attachments/assets/519fcb20-ab8c-4af3-9185-0953b3ba7b81

 [!NOTE]
 Using RubyLLM? Share your story! Takes 5 minutes.

---

 23 providers. One API.

Build with the models you want. Move between hosted and local providers without rewriting your application, or connect an OpenAI-compatible endpoint.

Browse models and pricing · Connect a provider

 A complete AI framework for Ruby

More than a client for model APIs. RubyLLM gives your application the conventions, the runtime, and every piece in between, designed to work together. Everything below ships in RubyLLM 2.1.

 Conversations

 Chat: Conversational AI with RubyLLM.chat
 Streaming: Real-time responses with blocks
 Attachments: Ask about images, videos, audio, PDFs, and other documents with with:
 Structured output: Define a Ruby schema and read the result with response.parsed
 Extended thinking: Control, view, and persist model deliberation
 Citations: Normalized source citations from documents, search, and grounding
 Prompt caching: Turn on the provider's cache with with_caching and cache_until_here
 Compaction: Let providers condense long conversations with with_compaction
 Token counting: Count a request before you send it with count_tokens
 Fallbacks and cancellation: Retry on backup models with with_fallbacks, stop a run with cancel

 Tools and agents

 Tools: Let AI call your Ruby methods
 Tool approval: Park a run until a human approves with requires_approval
 Provider tools: Web search, code execution, and MCP connectors with with_provider_tools
 MCP: Connect agents to your systems with server classes in app/mcp, per-user inputs, tool filtering, and OAuth with RubyLLM::MCP
 Agents: Reusable assistants with RubyLLM::Agent
 The agentic loop: Drive it yourself with ask_later, step, and complete?
 Prompt templates: ERB prompts in app/prompts, rendered with RubyLLM.render_prompt
 Workflows: Correlate multi-agent runs in your telemetry with RubyLLM.workflow
 Evaluations: Reusable datasets, model criteria, and Ruby assertions with RubyLLM::Evaluation
 Judgments: Probabilities, choices, and scores with RubyLLM::Judge and RubyLLM.judge

 Individual operations

 Image generation: Create images with RubyLLM.paint
 Video generation: Create videos with RubyLLM.animate
 Audio: Transcribe speech with RubyLLM.transcribe and generate it with RubyLLM.speak
 OCR: Turn documents into markdown with RubyLLM.ocr
 Embeddings: Generate embeddings with RubyLLM.embed
 R

Top issues

Discussions

Latest release

RubyLLM 2.1.1 fixes fresh installs that today's faraday-net_http 3.5.0 release broke, connects to MCP servers that predate the 2026-07-28 revision, and keeps batch embeddings paired with the right inputs.

sh
bundle add ruby_llm --version 2.1.1


Already on 2.1? Run bundle update ruby_llm. No schema or code changes are needed.

 Fixed

- Install RubyLLM with the latest faraday-net_http. faraday-net_http 3.5.0 falls outside the range every Faraday from 2.0.1 to 2.14.4 accepts, so a fresh bundle install resolved Faraday 2.0.0, which loads no default adapter, and every request failed with :net_ht