One chat object, 23 providers: how RubyLLM hides the provider split

Every provider is an environment variable, not an adapter class

The design bet is that a provider is a configuration choice, not a code path. The README lists the providers: OpenAI, Azure, xAI, Anthropic, Gemini, VertexAI, Bedrock, Cohere, DeepSeek, Hetzner, Meta, MiniMax, Mistral, Moonshot AI, Ollama, Ollama Cloud, OpenRouter, Perplexity, GPUStack, ElevenLabs, Deepgram, TypeSafe, Z.ai, and any OpenAI-compatible API.

The README also lets you connect any OpenAI-compatible endpoint, so the provider list is a floor rather than a ceiling. The cost is that capability is not uniform.

One chat object carries files, streams and tools without switching objects

RubyLLM.chat returns a chat object, and every later step stays on that object. Files arrive through the with: argument, which the README's Rails example uses for a PDF, and the feature list covers images, videos and documents. Streaming works with blocks. That single object is the actual mechanism: nothing is re-opened per modality, so a conversation that begins as text can take a screenshot on turn three without the caller learning a different class.

It ships under the MIT licence, and the last push to main was on 2026-11-02 following the 2.1.1 release of 2026-10-11.

Install first, then ask one question

The README does not carry a gem install line. It sends readers to the Getting Started page at rubyllm.com/getting-started/ and links a Connect a provider page for configuration. Then the smallest useful program is one line:

RubyLLM.chat.ask "What's the best way to learn Ruby?"

If that returns text, provider switching is already working. To attach files, pass them with `with:`, as the README's Rails example does:

chat = Chat.create! model: "gpt-6-luna"
chat.ask "What's in this file?", with: "report.pdf"

The verification step is deliberately unglamorous: check that the returned object is chat and that a second ask on the same object still answers, because that second call is where a stateless wrapper would fall apart.

Tools, agents and schemas sit on the same object

Tools let the model call your Ruby methods. RubyLLM::Agent defines reusable assistants: the README's SupportAgent declares instructions, lives in app/agents/support_agent.rb, and is called with SupportAgent.new.ask, which tells you where a Rails app is meant to put it.

Structured output means defining a Ruby schema and reading the result with response.parsed. Judgments use RubyLLM::Judge and RubyLLM.judge, which return probabilities, choices and scores, so a classifier is a class definition rather than a prompt plus a regex.

The catch is that this surface is broad. Paint, animate, transcribe, speak, ocr, rerank, embed and moderate each target a different vendor capability, and the README's own framing of a RAG app sits next to a provider list where no single vendor offers all of them. Expect to hold the model choice per feature rather than once globally.

Evaluations are available on main, not in the gem

This is worth knowing before you plan a test suite. The feature list marks evaluations as (main), and the README states plainly that evaluations are available on main and points to the development installation guide under rubyllm.com/next/getting-started/. The released gem, now at 2.1.1, is not where they live.

The shape is sensible. A dataset YAML holds cases with inputs and expected_output, a Ruby class extends RubyLLM::Evaluation and defines perform, and report.passed? plus report.cost.total come back from SupportEvaluation.run. Correctness is judged on meaning by default, so reworded answers pass, and you can swap in Ruby assertions or a different evaluator agent.

For a team that wants reproducible agent checks in CI today, that means tracking main, or writing your own assertions until the evaluation guides at rubyllm.com/next/evaluations/ reach a release.

Where Langchain-style graph orchestration differs

RubyLLM competes less with orchestration frameworks than with the raw HTTP clients most Ruby teams would otherwise write by hand. A pipeline framework models chains, nodes and branching graphs, and you assemble a program out of those units; RubyLLM centres on the model call and hangs tools, agents and schemas off it, leaving orchestration to your own Ruby control flow. That is why the agentic loop is exposed as ask_later, step and complete? rather than wrapped in a graph abstraction.

The practical difference shows up in debugging. With explicit graph nodes you can name each step in a trace; with RubyLLM the steps are your own methods, which means your logs carry the detail. In exchange, there is no built-in graph viewer to fall back on.

The Rails fit is real, and so is the provider surface

Three pieces decide this for a Rails shop: agent classes filed under app/agents, and cost reporting through report.cost.total. Rubocop, RSpec, Codecov and a gemfiles directory with an Appraisals file sit in the repository root, which reads like an ordinary well-run Ruby gem rather than a framework that wants to own your build.

Against that, provider tools (web search, code execution and MCP connectors via with_provider_tools) resolve to whichever vendor you configured. A team standardising on one hosted vendor gets the widest set of them.

Editorial conclusion

Adopt RubyLLM if your team writes Rails and wants to switch providers without rewriting call sites, and skip it if you need agent evaluations inside a released gem today, because evaluations live on main. Verify two things before writing the first feature: that every provider your application needs is in the README's list of 23, and that the released gem (2.1.1) already covers the calls you planned, since image, video, audio and rerank verbs each depend on the vendor you configure. Start from RubyLLM.chat.ask and confirm provider switching there.

Frequently asked questions

Official sources

1. crmne/ruby_llm on GitHub
2. License: MIT
3. Project website
4. README
5. Releases