module RubyLLM

RubyLLM is a Ruby interface to large language models. One API for OpenAI, Anthropic, Google, AWS, and every other major provider. These pages document every public class and method; the guides at rubyllm.com show how to build things with them.

RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
end

chat = RubyLLM.chat
chat.ask "What is the capital of France?"

Start here

Chat is the heart of the library. ::chat starts a conversation, and Chat#ask sends a message and returns a Message. Everything else builds on this: attachments, streaming, structured output, and tool calls.

Tool gives the model abilities. Subclass it, declare parameters, implement execute, and pass it to Chat#with_tools. Agent packages a configured chat (model, instructions, tools, schema) into a reusable class.

Beyond chat

::paint generates images (Image)
::embed turns text into vectors (Embedding)
::transcribe converts audio to text (Transcription)
::speak converts text to audio (Speech)
::moderate screens content (Moderation)
::batch processes many chats at lower cost (Batch)
::upload manages provider files (UploadedFile)

Rails

acts_as_chat persists conversations to Active Record, with siblings for messages, tool calls, models, and batches. See ActiveRecord::ActsAs.

`Configuration` and models

Configuration holds global settings, set through ::configure. Context scopes overrides to a group of calls. Models finds, filters, and prices every known model.

Provider errors raise subclasses of Error, one per HTTP status family.

Constants

VERSION: The version of the ruby_llm gem, as a string.

Public Class Methods

batch (chats)

Source

# File lib/ruby_llm.rb, line 135
def batch(chats)
  Batch.submit(chats)
end

Submits chats staged with Chat#ask_later as a provider-side batch and returns a Batch. Look up an existing batch with Batch.find.

chats = documents.map do |doc|
  RubyLLM.chat(model: 'claude-haiku-4-5').ask_later(doc.text)
end
batch = RubyLLM.batch(chats)

chat (...)

Source

# File lib/ruby_llm.rb, line 123
def chat(...)
  Chat.new(...)
end

Creates a Chat conversation. Arguments are forwarded to Chat.new: model:, provider:, assume_model_exists:, and context:. With no arguments, uses the configured default model.

chat = RubyLLM.chat
chat.ask "What is the capital of France?"

chat = RubyLLM.chat(model: 'claude-sonnet-4-5')

config ()

Source

# File lib/ruby_llm.rb, line 255
def config
  @config ||= Configuration.new
end

Returns the global Configuration instance.

configure () { |config| ... }

Source

# File lib/ruby_llm.rb, line 250
def configure
  yield config
end

Yields the global configuration for block-style setup. Call this once at startup to set API keys and defaults.

RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
end

context () { |context_config| ... }

Source

# File lib/ruby_llm.rb, line 108
def context
  context_config = config.dup
  yield context_config if block_given?
  Context.new(context_config)
end

Returns a Context, an isolated set of configuration overrides. Duplicates the global configuration and yields the copy if a block is given. The context offers the same entry points as the top-level RubyLLM module (Context#chat, Context#embed, and so on) using its own configuration.

context = RubyLLM.context do |config|
  config.openai_api_key = 'sk-customer-specific-key'
end
context.chat.ask "Hello"

download (...)

Source

# File lib/ruby_llm.rb, line 205
def download(...)
  UploadedFile.download(...)
end

Downloads the content of a provider-managed file. Arguments are forwarded to UploadedFile.download.

content = RubyLLM.download(file.id)

embed (...)

Source

# File lib/ruby_llm.rb, line 146
def embed(...)
  Embedding.embed(...)
end

Generates a vector embedding for a text, or one embedding per element when given an array of strings. Returns an Embedding. Arguments are forwarded to Embedding.embed.

embedding = RubyLLM.embed("Ruby is a programmer's best friend")
embedding.vectors # => [0.018, -0.027, ...]

models ()

Source

# File lib/ruby_llm.rb, line 230
def models
  Models.instance
end

Returns the Models registry, used to browse, find, and refresh model metadata.

RubyLLM.models.find("claude-haiku-4-5")
RubyLLM.models.refresh!

moderate (...)

Source

# File lib/ruby_llm.rb, line 156
def moderate(...)
  Moderation.moderate(...)
end

Checks text or image attachments against the provider’s moderation model and returns a Moderation result. Arguments are forwarded to Moderation.moderate.

result = RubyLLM.moderate("Some user input text")
result.flagged? # => false

paint (...)

Source

# File lib/ruby_llm.rb, line 166
def paint(...)
  Image.paint(...)
end

Generates an image from a text prompt and returns an Image. Arguments are forwarded to Image.paint.

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

providers ()

Source

# File lib/ruby_llm.rb, line 239
def providers
  Provider.providers.values
end

Returns the registered provider classes.

RubyLLM.providers.map(&:slug)
# => ["anthropic", "azure", "bedrock", ...]

render_prompt (name, **locals)

Source

# File lib/ruby_llm.rb, line 220
def render_prompt(name, **locals)
  Prompt.render(name, **locals)
end

Renders the ERB prompt template name and returns the result as a String. The name resolves to a .txt.erb file under app/prompts. Keyword arguments become locals in the template.

instructions = RubyLLM.render_prompt(
  "support/instructions",
  product_name: "BillingHub"
)
chat.with_instructions(instructions)

Raises PromptNotFoundError if the template file does not exist.

speak (...)

Source

# File lib/ruby_llm.rb, line 176
def speak(...)
  Speech.speak(...)
end

Synthesizes speech from text and returns a Speech. Arguments are forwarded to Speech.speak.

speech = RubyLLM.speak "Hello, welcome to RubyLLM!"
speech.save("welcome.mp3")

transcribe (...)

Source

# File lib/ruby_llm.rb, line 186
def transcribe(...)
  Transcription.transcribe(...)
end

Transcribes an audio file and returns a Transcription. Arguments are forwarded to Transcription.transcribe.

transcription = RubyLLM.transcribe("meeting.wav")
transcription.text

upload (...)

Source

# File lib/ruby_llm.rb, line 196
def upload(...)
  UploadedFile.upload(...)
end

Uploads a file to a provider and returns an UploadedFile that can be reused across chats. Arguments are forwarded to UploadedFile.upload.

file = RubyLLM.upload("document.pdf", provider: :anthropic)
chat.ask "Summarize this document", with: file

module RubyLLM

Start here

Beyond chat

Rails

Configuration and models

`Configuration` and models