Build with RubyLLM

Use the application's installed RubyLLM version and existing conventions. This skill describes the 2.x API; features marked 2.1 need RubyLLM 2.1 or later. Read Gemfile.lock, or inspect the installed gem before choosing an API:

bundle exec ruby -rruby_llm -e 'puts RubyLLM::VERSION'
bundle show ruby_llm

For a 1.x application, use its version's documentation and keep the requested change on 1.x unless the user asks for an upgrade. Adding an AI feature does not require upgrading the application's framework.

Choose the API for the task

RubyLLM has two public API families: conversations use chats, messages, tools, agents, structured output, streaming, and loop control; individual operations use paint, animate, speak, transcribe, ocr, moderate, embed, rerank, judge, tokenize, and research. Individual operations return typed results without requiring a chat. Some stream or have an asynchronous lifecycle.

Providers supply service endpoints, authentication, catalogs, and protocol selection. Protocols translate requests and responses. Both API families use this integration layer and shared services for model selection, configuration, accounting, and instrumentation. Build against the public API and let RubyLLM handle the service formats.

Rails integration adds persistence, attachments, streaming UI support, jobs, and generators around the same Ruby API.

Find the relevant API

The installed gem's public method signatures and RDoc describe the code the application actually runs. Use them when online documentation differs. Find the matching version through RubyLLM's documentation. The root site documents the latest stable release. Unreleased changes on main are under rubyllm.com/next/, and 1.x under rubyllm.com/v1/.

Read the relevant page instead of loading the entire documentation site: