Module: RubyLLM

Defined in:
lib/ruby_llm.rb,
lib/ruby_llm/ocr.rb,
lib/ruby_llm/chat.rb,
lib/ruby_llm/cost.rb,
lib/ruby_llm/tool.rb,
lib/ruby_llm/agent.rb,
lib/ruby_llm/batch.rb,
lib/ruby_llm/chunk.rb,
lib/ruby_llm/error.rb,
lib/ruby_llm/image.rb,
lib/ruby_llm/model.rb,
lib/ruby_llm/video.rb,
lib/ruby_llm/models.rb,
lib/ruby_llm/prompt.rb,
lib/ruby_llm/rerank.rb,
lib/ruby_llm/speech.rb,
lib/ruby_llm/tokens.rb,
lib/ruby_llm/context.rb,
lib/ruby_llm/message.rb,
lib/ruby_llm/railtie.rb,
lib/ruby_llm/version.rb,
lib/ruby_llm/citation.rb,
lib/ruby_llm/fallback.rb,
lib/ruby_llm/protocol.rb,
lib/ruby_llm/provider.rb,
lib/ruby_llm/thinking.rb,
lib/ruby_llm/workflow.rb,
lib/ruby_llm/embedding.rb,
lib/ruby_llm/tool_call.rb,
lib/ruby_llm/video_job.rb,
lib/ruby_llm/attachment.rb,
lib/ruby_llm/moderation.rb,
lib/ruby_llm/research_job.rb,
lib/ruby_llm/speech_chunk.rb,
lib/ruby_llm/tokenization.rb,
lib/ruby_llm/configuration.rb,
lib/ruby_llm/model/pricing.rb,
lib/ruby_llm/models/schema.rb,
lib/ruby_llm/providers/xai.rb,
lib/ruby_llm/support/utils.rb,
lib/ruby_llm/transcription.rb,
lib/ruby_llm/uploaded_file.rb,
lib/ruby_llm/cached_content.rb,
lib/ruby_llm/models/aliases.rb,
lib/ruby_llm/search_results.rb,
lib/ruby_llm/downloaded_file.rb,
lib/ruby_llm/files/mime_type.rb,
lib/ruby_llm/models/registry.rb,
lib/ruby_llm/protocols/files.rb,
lib/ruby_llm/providers/azure.rb,
lib/ruby_llm/accounting/usage.rb,
lib/ruby_llm/model/modalities.rb,
lib/ruby_llm/protocols/cohere.rb,
lib/ruby_llm/protocols/gemini.rb,
lib/ruby_llm/providers/cohere.rb,
lib/ruby_llm/providers/gemini.rb,
lib/ruby_llm/providers/ollama.rb,
lib/ruby_llm/providers/openai.rb,
lib/ruby_llm/server_tool_call.rb,
lib/ruby_llm/embedding_request.rb,
lib/ruby_llm/providers/bedrock.rb,
lib/ruby_llm/providers/mistral.rb,
lib/ruby_llm/model/pricing_tier.rb,
lib/ruby_llm/protocol/streaming.rb,
lib/ruby_llm/protocols/converse.rb,
lib/ruby_llm/protocols/deepgram.rb,
lib/ruby_llm/providers/deepgram.rb,
lib/ruby_llm/providers/deepseek.rb,
lib/ruby_llm/providers/gpustack.rb,
lib/ruby_llm/providers/vertexai.rb,
lib/ruby_llm/providers/xai/chat.rb,
lib/ruby_llm/support/deprecator.rb,
lib/ruby_llm/active_record/batch.rb,
lib/ruby_llm/active_record/model.rb,
lib/ruby_llm/active_record/usage.rb,
lib/ruby_llm/protocols/anthropic.rb,
lib/ruby_llm/protocols/responses.rb,
lib/ruby_llm/protocols/xai/files.rb,
lib/ruby_llm/providers/anthropic.rb,
lib/ruby_llm/support/inspectable.rb,
lib/ruby_llm/transcription_chunk.rb,
lib/ruby_llm/protocols/cohere/ocr.rb,
lib/ruby_llm/protocols/elevenlabs.rb,
lib/ruby_llm/providers/azure/chat.rb,
lib/ruby_llm/providers/elevenlabs.rb,
lib/ruby_llm/providers/openrouter.rb,
lib/ruby_llm/providers/perplexity.rb,
lib/ruby_llm/providers/xai/images.rb,
lib/ruby_llm/providers/xai/models.rb,
lib/ruby_llm/providers/xai/speech.rb,
lib/ruby_llm/providers/xai/videos.rb,
lib/ruby_llm/tools/provider_tools.rb,
lib/ruby_llm/transport/connection.rb,
lib/ruby_llm/active_record/acts_as.rb,
lib/ruby_llm/chat/tool_concurrency.rb,
lib/ruby_llm/protocols/azure/files.rb,
lib/ruby_llm/protocols/cohere/chat.rb,
lib/ruby_llm/protocols/gemini/chat.rb,
lib/ruby_llm/providers/azure/audio.rb,
lib/ruby_llm/providers/azure/media.rb,
lib/ruby_llm/providers/mistral/ocr.rb,
lib/ruby_llm/providers/ollama/chat.rb,
lib/ruby_llm/model/pricing_category.rb,
lib/ruby_llm/protocols/cohere/media.rb,
lib/ruby_llm/protocols/cohere/tools.rb,
lib/ruby_llm/protocols/gemini/files.rb,
lib/ruby_llm/protocols/gemini/media.rb,
lib/ruby_llm/protocols/gemini/tools.rb,
lib/ruby_llm/protocols/interactions.rb,
lib/ruby_llm/protocols/invoke_model.rb,
lib/ruby_llm/protocols/openai/files.rb,
lib/ruby_llm/providers/azure/cohere.rb,
lib/ruby_llm/providers/azure/images.rb,
lib/ruby_llm/providers/azure/models.rb,
lib/ruby_llm/providers/azure/videos.rb,
lib/ruby_llm/providers/bedrock/auth.rb,
lib/ruby_llm/providers/mistral/chat.rb,
lib/ruby_llm/providers/ollama/media.rb,
lib/ruby_llm/providers/ollama_cloud.rb,
lib/generators/ruby_llm/provider/cli.rb,
lib/ruby_llm/active_record/tool_call.rb,
lib/ruby_llm/protocols/bedrock/files.rb,
lib/ruby_llm/protocols/cohere/models.rb,
lib/ruby_llm/protocols/cohere/rerank.rb,
lib/ruby_llm/protocols/converse/chat.rb,
lib/ruby_llm/protocols/gemini/caches.rb,
lib/ruby_llm/protocols/gemini/images.rb,
lib/ruby_llm/protocols/gemini/models.rb,
lib/ruby_llm/protocols/gemini/speech.rb,
lib/ruby_llm/protocols/gemini/videos.rb,
lib/ruby_llm/protocols/mistral/files.rb,
lib/ruby_llm/providers/deepseek/chat.rb,
lib/ruby_llm/providers/gpustack/chat.rb,
lib/ruby_llm/providers/mistral/media.rb,
lib/ruby_llm/providers/ollama/models.rb,
lib/ruby_llm/providers/openai/models.rb,
lib/ruby_llm/providers/xai/responses.rb,
lib/ruby_llm/support/instrumentation.rb,
lib/ruby_llm/transcription/wav_audio.rb,
lib/ruby_llm/protocols/anthropic/chat.rb,
lib/ruby_llm/protocols/bedrock/rerank.rb,
lib/ruby_llm/protocols/cohere/batches.rb,
lib/ruby_llm/protocols/converse/media.rb,
lib/ruby_llm/protocols/deepseek/files.rb,
lib/ruby_llm/protocols/gemini/batches.rb,
lib/ruby_llm/protocols/openai/batches.rb,
lib/ruby_llm/protocols/responses/chat.rb,
lib/ruby_llm/protocols/vertexai/files.rb,
lib/ruby_llm/providers/bedrock/mantle.rb,
lib/ruby_llm/providers/bedrock/models.rb,
lib/ruby_llm/providers/gpustack/media.rb,
lib/ruby_llm/providers/mistral/models.rb,
lib/ruby_llm/providers/mistral/speech.rb,
lib/ruby_llm/protocol/binary_streaming.rb,
lib/ruby_llm/protocols/anthropic/files.rb,
lib/ruby_llm/protocols/anthropic/media.rb,
lib/ruby_llm/protocols/anthropic/tools.rb,
lib/ruby_llm/protocols/bedrock/batches.rb,
lib/ruby_llm/protocols/cohere/datasets.rb,
lib/ruby_llm/protocols/deepgram/models.rb,
lib/ruby_llm/protocols/deepgram/speech.rb,
lib/ruby_llm/protocols/gpustack/videos.rb,
lib/ruby_llm/protocols/mistral/content.rb,
lib/ruby_llm/protocols/responses/media.rb,
lib/ruby_llm/protocols/responses/tools.rb,
lib/ruby_llm/providers/azure/responses.rb,
lib/ruby_llm/providers/gpustack/models.rb,
lib/ruby_llm/providers/gpustack/speech.rb,
lib/ruby_llm/providers/openrouter/chat.rb,
lib/ruby_llm/providers/perplexity/chat.rb,
lib/ruby_llm/providers/vertexai/gemini.rb,
lib/ruby_llm/providers/vertexai/models.rb,
lib/ruby_llm/providers/vertexai/videos.rb,
lib/ruby_llm/active_record/chat_methods.rb,
lib/ruby_llm/protocols/anthropic/models.rb,
lib/ruby_llm/protocols/chat_completions.rb,
lib/ruby_llm/protocols/cohere/streaming.rb,
lib/ruby_llm/protocols/converse/batches.rb,
lib/ruby_llm/protocols/elevenlabs/flows.rb,
lib/ruby_llm/protocols/gemini/streaming.rb,
lib/ruby_llm/protocols/openrouter/files.rb,
lib/ruby_llm/protocols/perplexity/files.rb,
lib/ruby_llm/protocols/vertexai/ranking.rb,
lib/ruby_llm/protocols/xai/tokenization.rb,
lib/ruby_llm/providers/azure/embeddings.rb,
lib/ruby_llm/providers/openai/responses.rb,
lib/ruby_llm/providers/openrouter/media.rb,
lib/ruby_llm/providers/perplexity/media.rb,
lib/ruby_llm/providers/vertexai/mistral.rb,
lib/ruby_llm/providers/xai/capabilities.rb,
lib/ruby_llm/transport/error_middleware.rb,
lib/ruby_llm/transport/usage_middleware.rb,
lib/ruby_llm/protocol/stream_accumulator.rb,
lib/ruby_llm/protocols/anthropic/batches.rb,
lib/ruby_llm/protocols/cohere/embeddings.rb,
lib/ruby_llm/protocols/elevenlabs/assets.rb,
lib/ruby_llm/protocols/elevenlabs/models.rb,
lib/ruby_llm/protocols/elevenlabs/speech.rb,
lib/ruby_llm/protocols/gemini/embeddings.rb,
lib/ruby_llm/protocols/interactions/chat.rb,
lib/ruby_llm/protocols/perplexity/router.rb,
lib/ruby_llm/protocols/responses/batches.rb,
lib/ruby_llm/protocols/vertexai/research.rb,
lib/ruby_llm/providers/openrouter/images.rb,
lib/ruby_llm/providers/openrouter/models.rb,
lib/ruby_llm/providers/openrouter/speech.rb,
lib/ruby_llm/providers/openrouter/videos.rb,
lib/ruby_llm/providers/perplexity/models.rb,
lib/ruby_llm/providers/xai/reported_cost.rb,
lib/ruby_llm/providers/xai/transcription.rb,
lib/generators/ruby_llm/generator_helpers.rb,
lib/generators/ruby_llm/provider/scaffold.rb,
lib/ruby_llm/protocols/bedrock/guardrails.rb,
lib/ruby_llm/protocols/converse/streaming.rb,
lib/ruby_llm/protocols/gpustack/responses.rb,
lib/ruby_llm/protocols/interactions/tools.rb,
lib/ruby_llm/protocols/openrouter/batches.rb,
lib/ruby_llm/providers/azure/capabilities.rb,
lib/ruby_llm/providers/deepseek/responses.rb,
lib/ruby_llm/providers/mistral/embeddings.rb,
lib/ruby_llm/providers/vertexai/anthropic.rb,
lib/ruby_llm/active_record/message_methods.rb,
lib/ruby_llm/active_record/payload_helpers.rb,
lib/ruby_llm/protocols/anthropic/streaming.rb,
lib/ruby_llm/protocols/cohere/tokenization.rb,
lib/ruby_llm/protocols/responses/approvals.rb,
lib/ruby_llm/protocols/responses/streaming.rb,
lib/ruby_llm/providers/gemini/capabilities.rb,
lib/ruby_llm/providers/gpustack/embeddings.rb,
lib/ruby_llm/providers/ollama_cloud/models.rb,
lib/ruby_llm/providers/openai/capabilities.rb,
lib/ruby_llm/providers/vertexai/embeddings.rb,
lib/generators/ruby_llm/tool/tool_generator.rb,
lib/ruby_llm/protocols/anthropic/embeddings.rb,
lib/ruby_llm/protocols/bedrock/async_videos.rb,
lib/ruby_llm/protocols/cohere/transcription.rb,
lib/ruby_llm/protocols/gemini/transcription.rb,
lib/ruby_llm/protocols/interactions/content.rb,
lib/ruby_llm/protocols/openrouter/responses.rb,
lib/ruby_llm/protocols/responses/compaction.rb,
lib/ruby_llm/providers/bedrock/capabilities.rb,
lib/ruby_llm/providers/mistral/capabilities.rb,
lib/ruby_llm/providers/openrouter/streaming.rb,
lib/ruby_llm/providers/xai/chat_completions.rb,
lib/ruby_llm/transport/websocket_connection.rb,
lib/ruby_llm/protocols/chat_completions/chat.rb,
lib/ruby_llm/protocols/cohere/batch_requests.rb,
lib/ruby_llm/protocols/gpustack/tokenization.rb,
lib/ruby_llm/protocols/mistral/conversations.rb,
lib/ruby_llm/providers/deepseek/capabilities.rb,
lib/ruby_llm/providers/mistral/conversations.rb,
lib/ruby_llm/providers/mistral/transcription.rb,
lib/ruby_llm/providers/openrouter/embeddings.rb,
lib/ruby_llm/providers/perplexity/embeddings.rb,
lib/ruby_llm/providers/vertexai/capabilities.rb,
lib/generators/ruby_llm/agent/agent_generator.rb,
lib/ruby_llm/active_record/attachment_helpers.rb,
lib/ruby_llm/protocols/chat_completions/media.rb,
lib/ruby_llm/protocols/chat_completions/tools.rb,
lib/ruby_llm/protocols/deepgram/transcription.rb,
lib/ruby_llm/protocols/elevenlabs/flows/media.rb,
lib/ruby_llm/protocols/interactions/streaming.rb,
lib/ruby_llm/providers/anthropic/capabilities.rb,
lib/ruby_llm/providers/azure/chat_completions.rb,
lib/ruby_llm/providers/bedrock/mantle/voxtral.rb,
lib/ruby_llm/providers/gpustack/transcription.rb,
lib/ruby_llm/providers/vertexai/embed_content.rb,
lib/ruby_llm/providers/vertexai/transcription.rb,
lib/ruby_llm/protocols/chat_completions/images.rb,
lib/ruby_llm/protocols/chat_completions/models.rb,
lib/ruby_llm/protocols/chat_completions/rerank.rb,
lib/ruby_llm/protocols/chat_completions/speech.rb,
lib/ruby_llm/protocols/elevenlabs/flows/images.rb,
lib/ruby_llm/protocols/elevenlabs/flows/videos.rb,
lib/ruby_llm/providers/vertexai/gemini/batches.rb,
lib/generators/ruby_llm/schema/schema_generator.rb,
lib/ruby_llm/protocols/chat_completions/batches.rb,
lib/ruby_llm/protocols/converse/thinking_stream.rb,
lib/ruby_llm/protocols/elevenlabs/transcription.rb,
lib/ruby_llm/protocols/gemini/embedding_batches.rb,
lib/ruby_llm/protocols/mistral/multi_completion.rb,
lib/ruby_llm/protocols/openrouter/transcription.rb,
lib/ruby_llm/protocols/responses/token_counting.rb,
lib/ruby_llm/providers/bedrock/mantle/anthropic.rb,
lib/ruby_llm/providers/bedrock/mantle/responses.rb,
lib/ruby_llm/providers/mistral/chat_completions.rb,
lib/ruby_llm/protocols/gemini/file_transcription.rb,
lib/ruby_llm/protocols/gemini/live_transcription.rb,
lib/ruby_llm/protocols/vertexai/batch_prediction.rb,
lib/ruby_llm/providers/vertexai/chat_completions.rb,
lib/generators/ruby_llm/chat_ui/chat_ui_generator.rb,
lib/generators/ruby_llm/install/install_generator.rb,
lib/generators/ruby_llm/upgrade/upgrade_generator.rb,
lib/generators/ruby_llm/upgrade/upgrade_migration.rb,
lib/ruby_llm/protocols/chat_completions/streaming.rb,
lib/ruby_llm/protocols/interactions/transcription.rb,
lib/ruby_llm/protocols/mistral/conversations/chat.rb,
lib/ruby_llm/providers/vertexai/anthropic/batches.rb,
lib/generators/ruby_llm/upgrade/legacy_content_sql.rb,
lib/ruby_llm/protocols/chat_completions/embeddings.rb,
lib/ruby_llm/protocols/chat_completions/moderation.rb,
lib/ruby_llm/protocols/xai/streaming_transcription.rb,
lib/ruby_llm/providers/vertexai/live_transcription.rb,
lib/ruby_llm/protocols/invoke_model/nova_embeddings.rb,
lib/ruby_llm/protocols/mistral/conversations/images.rb,
lib/ruby_llm/providers/xai/chat_completions/batches.rb,
lib/ruby_llm/protocols/invoke_model/stability_images.rb,
lib/ruby_llm/protocols/vertexai/embedding_prediction.rb,
lib/generators/ruby_llm/upgrade/online_copy_migration.rb,
lib/ruby_llm/protocols/chat_completions/transcription.rb,
lib/ruby_llm/protocols/invoke_model/cohere_embeddings.rb,
lib/ruby_llm/protocols/invoke_model/embedding_batches.rb,
lib/ruby_llm/providers/azure/chat_completions/batches.rb,
lib/ruby_llm/protocols/mistral/conversations/streaming.rb,
lib/ruby_llm/providers/bedrock/mantle/chat_completions.rb,
lib/ruby_llm/protocols/deepgram/streaming_transcription.rb,
lib/ruby_llm/providers/mistral/chat_completions/batches.rb,
lib/ruby_llm/providers/vertexai/chat_completions/batches.rb,
lib/ruby_llm/protocols/chat_completions/embedding_batches.rb,
lib/ruby_llm/protocols/elevenlabs/streaming_transcription.rb,
lib/ruby_llm/protocols/invoke_model/titan_text_embeddings.rb,
lib/generators/ruby_llm/upgrade/online_copy_migration/data.rb,
lib/ruby_llm/protocols/vertexai/embedding_prediction/results.rb,
lib/generators/ruby_llm/upgrade/online_copy_migration/journal.rb,
lib/ruby_llm/protocols/vertexai/embedding_prediction/requests.rb,
lib/ruby_llm/protocols/invoke_model/titan_multimodal_embeddings.rb,
lib/generators/ruby_llm/upgrade/online_copy_migration/verification.rb

Overview

RubyLLM is an AI framework for Ruby and Rails. Build conversations and agents, generate media, process documents, and work with model providers through one Ruby API. The guides at https://rubyllm.com/ introduce each feature; this reference documents its classes, arguments, and results.

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

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

Conversations, tools, and agents

RubyLLM.chat returns a Chat that holds the conversation. Chat#ask accepts text and attachments, runs tools as needed, and returns a Message. Give it a block to receive Chunk objects as the response streams:

chat.ask("Summarize this report", with: "report.pdf") do |chunk|
print chunk.content
end

Configure the request with chainable methods:

  • Chat#with_schema requests structured output; Message#parsed reads it.
  • Chat#with_thinking sets thinking effort, budget, or display preferences.
  • Chat#with_citations requests source citations, read through Message#citations.
  • Chat#with_fallbacks tries other models when a request fails.
  • Chat#with_caching enables prompt caching; Chat#cache_until_here marks a reusable prefix. Chat#with_compaction manages long conversations.

Subclass Tool and implement execute to give the model an application action. Tool.requires_approval pauses execution for a human decision; Chat#approve and Chat#deny record it. Chat#with_provider_tools enables provider-executed tools such as web search, code execution, and remote MCP. Their calls appear as ServerToolCall values, with Citation values for sources.

Agent defines a reusable configuration with model, instructions, tools, schema, and runtime inputs. Chat#ask_later, Chat#generate, Chat#run_tools, and Chat#step expose the conversation loop for jobs and application logic.

Images, video, and speech

Individual operations do not require a chat. Image, Video, and Speech results share save(path) and to_blob:

RubyLLM.paint("A red panda coding Ruby, watercolor").save("panda.png")
RubyLLM.animate("A paper boat sailing down a gutter").save("boat.mp4")
RubyLLM.speak("Welcome to RubyLLM.").save("welcome.mp3")

Image.paint accepts source images and masks for editing. Video.animate accepts reference media, video edits, and extensions on supported models. RubyLLM.animate waits for the clip; RubyLLM.animate_later returns a VideoJob that you can poll. Speech.speak also streams SpeechChunk objects while retaining the complete audio result.

Documents, audio, and retrieval

transcript = RubyLLM.transcribe("meeting.wav")
document = RubyLLM.ocr("report.pdf", pages: [0, 1])
embedding = RubyLLM.embed("Ruby is a programmer's best friend")

Transcription provides text, timestamps, and speaker information when the model reports them; streaming yields TranscriptionChunk objects. OCR returns document pages and combined markdown. Embedding returns vectors for text or supported media, and RubyLLM.rerank returns a Rerank whose results order documents by relevance. SearchResults lets a Tool return source documents that the model can cite.

RubyLLM.upload returns an UploadedFile for reuse across requests. RubyLLM.download returns a DownloadedFile with the same saving interface:

RubyLLM.download(file.id, provider: file.provider).save("report.pdf")

Tokenization, moderation, and research

RubyLLM.count_tokens and Chat#count_tokens count a model request without generating a response. RubyLLM.tokenize returns plain-text token IDs and a count as a Tokenization, excluding chat formatting and attachments.

result = RubyLLM.tokenize("Hello Ruby", model: "grok-4.3", provider: :xai)
result.ids
result.count

RubyLLM.moderate screens text and images, returning Moderation results with categories, scores, and flagged?. RubyLLM.research runs a hosted research task and returns its report as a Message; RubyLLM.research_later returns a ResearchJob for polling and cancellation. Hosted agent identities are selected separately from model IDs.

Batches, usage, and configuration

RubyLLM.batch submits staged chats or EmbeddingRequest objects for provider-side processing. Batch exposes progress, results, token usage, and cost. RubyLLM.cache creates a managed CachedContent resource for reuse with Chat#with_caching.

Tokens and Cost report usage and pricing. Chat totals include retries and attempts that produced no message. Provider-reported costs take precedence over estimates; unknown usage and prices remain nil. RubyLLM.workflow groups instrumentation from ordinary Ruby code into named Workflow steps.

RubyLLM.configure sets global Configuration; RubyLLM.context creates isolated settings for a request or tenant. Models finds, filters, and describes the model catalog. Provider supplies endpoints, authentication, and protocol selection; Protocol implements request and response formats. Error subclasses normalize provider failures.

Rails integration

ActiveRecord::ActsAs adds acts_as_chat and acts_as_message to your application's models. ActiveRecord::ChatMethods and ActiveRecord::MessageMethods provide the conversation API with persistence, Active Storage attachments, and support for Hotwire streaming and jobs. Approvals and cancellation survive requests and processes.

Your application owns chats and messages; RubyLLM owns usage, tool calls, models, and batches. Agent can create and reload your chat records through Agent.chat_model. Individual operations also work directly in Rails services and jobs.

Defined Under Namespace

Modules: Accounting, ActiveRecord, Files, Generators, Protocols, Providers, Support, Tools, Transport Classes: Agent, Attachment, BadRequestError, Batch, CachedContent, CancelledError, Chat, Chunk, Citation, Configuration, ConfigurationError, Context, ContextLengthExceededError, Cost, DeprecationError, DownloadedFile, Embedding, EmbeddingRequest, Error, Fallback, ForbiddenError, Image, InvalidRoleError, InvalidToolChoiceError, Message, Model, ModelNotFoundError, ModelRegistryError, Models, Moderation, OCR, OverloadedError, Parameter, PaymentRequiredError, PendingToolCallsError, Prompt, PromptNotFoundError, Protocol, Provider, Railtie, RateLimitError, Rerank, ResearchJob, SearchResults, ServerError, ServerToolCall, ServiceUnavailableError, Speech, SpeechChunk, Thinking, Tokenization, Tokens, Tool, ToolCall, ToolCallParseError, Transcription, TranscriptionChunk, UnauthorizedError, UnsupportedAttachmentError, UnsupportedServerToolError, UploadedFile, Video, VideoJob, Workflow

Constant Summary collapse

VERSION =

The version of the ruby_llm gem, as a string.

'2.0.0'

Class Method Summary collapse

Class Method Details

.animate ⇒ Object

Generates a video from a text prompt, blocks until the provider finishes rendering it, and returns a Video. Arguments are forwarded to Video.animate.

video = RubyLLM.animate("a paper boat sailing down a rainy gutter")
video.save("boat.mp4")


320
321
322
 
# File 'lib/ruby_llm.rb', line 320

def animate(...)
  Video.animate(...)
end

.animate_later ⇒ Object

Submits a video generation job and returns a VideoJob immediately, without waiting for the result. Arguments are forwarded to VideoJob.animate_later.

job = RubyLLM.animate_later("a paper boat sailing down a gutter")
job.wait
job.video.save("boat.mp4")


332
333
334
 
# File 'lib/ruby_llm.rb', line 332

def animate_later(...)
  VideoJob.animate_later(...)
end

.batch(chats) ⇒ Object

Submits requests staged with Chat#ask_later or ::embed_later as a provider-side batch and returns a Batch. A batch takes chats or embedding requests, not both. 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)


251
252
253
 
# File 'lib/ruby_llm.rb', line 251

def batch(chats)
  Batch.submit(chats)
end

.cache ⇒ Object

Creates a provider-side prompt cache and returns a CachedContent that chats can attach with Chat#with_caching. Arguments are forwarded to CachedContent.create.

cache = RubyLLM.cache(big_document, model: 'gemini-3.7-flash', ttl: 3600)
chat = RubyLLM.chat(model: 'gemini-3.7-flash').with_caching(id: cache)


410
411
412
 
# File 'lib/ruby_llm.rb', line 410

def cache(...)
  CachedContent.create(...)
end

.chat ⇒ Object

Creates a Chat conversation. Arguments are forwarded to Chat.new: model:, provider:, protocol:, 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-5')


220
221
222
 
# File 'lib/ruby_llm.rb', line 220

def chat(...)
  Chat.new(...)
end

.config ⇒ Object

Returns the global Configuration instance.



460
461
462
 
# File 'lib/ruby_llm.rb', line 460

def config
  @config ||= Configuration.new
end

.configure {|config| ... } ⇒ Object

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

Yields:



455
456
457
 
# File 'lib/ruby_llm.rb', line 455

def configure
  yield config
end

.context {|context_config| ... } ⇒ Object

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"

Yields:

  • (context_config) 


187
188
189
190
191
 
# File 'lib/ruby_llm.rb', line 187

def context
  context_config = config.dup
  yield context_config if block_given?
  Context.new(context_config)
end

.count_tokens(text, model: nil, provider: nil) ⇒ Object

Counts the tokens text would consume as a single user message, without requesting a completion. Builds a minimal Chat and delegates to Chat#count_tokens. Returns an Integer.

RubyLLM.count_tokens("What is the capital of France?", model: 'claude-haiku-4-5')


230
231
232
 
# File 'lib/ruby_llm.rb', line 230

def count_tokens(text, model: nil, provider: nil)
  chat(model: model, provider: provider).count_tokens(text)
end

.deprecator ⇒ Object

:nodoc:



168
169
170
 
# File 'lib/ruby_llm.rb', line 168

def deprecator # :nodoc:
  @deprecator ||= Support::Deprecator.new
end

.download ⇒ Object

Downloads a provider file and returns a DownloadedFile. Save it with DownloadedFile#save or read its bytes with DownloadedFile#to_blob. Arguments are forwarded to UploadedFile.download.

RubyLLM.download(file.id, provider: :openai).save("report.pdf")


399
400
401
 
# File 'lib/ruby_llm.rb', line 399

def download(...)
  UploadedFile.download(...)
end

.embed ⇒ Object

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, ...]


262
263
264
 
# File 'lib/ruby_llm.rb', line 262

def embed(...)
  Embedding.embed(...)
end

.embed_later(text, model: nil, provider: nil, dimensions: nil) ⇒ Object

Stages a text for embedding without contacting the provider, and returns an EmbeddingRequest. Submit an array of staged requests as a provider-side batch with ::batch; once the batch completes, each request's EmbeddingRequest#result holds its Embedding.

requests = texts.map { |text| RubyLLM.embed_later(text) }
batch = RubyLLM.batch(requests)


274
275
276
 
# File 'lib/ruby_llm.rb', line 274

def embed_later(text, model: nil, provider: nil, dimensions: nil)
  EmbeddingRequest.new(text, model:, provider:, dimensions:)
end

.instrument ⇒ Object

:nodoc:



172
173
174
 
# File 'lib/ruby_llm.rb', line 172

def instrument(...) # :nodoc:
  Support::Instrumentation.instrument(...)
end

.logger ⇒ Object

:nodoc:



464
465
466
467
468
469
470
 
# File 'lib/ruby_llm.rb', line 464

def logger # :nodoc:
  @logger ||= config.logger || Logger.new(
    config.log_file,
    progname: 'RubyLLM',
    level: config.log_level
  )
end

.models ⇒ Object

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

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


435
436
437
 
# File 'lib/ruby_llm.rb', line 435

def models
  Models.instance
end

.moderate ⇒ Object

Checks text or image attachments against the provider's moderation model and returns a Moderation result. Arguments are forwarded to Moderation.moderate. An explicitly selected provider can use a configured moderation resource without a model.

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


286
287
288
 
# File 'lib/ruby_llm.rb', line 286

def moderate(...)
  Moderation.moderate(...)
end

.ocr ⇒ Object

Extracts the text of a document or image and returns an OCR result. Arguments are forwarded to OCR.ocr.

ocr = RubyLLM.ocr("contract.pdf")
ocr.markdown


368
369
370
 
# File 'lib/ruby_llm.rb', line 368

def ocr(...)
  OCR.ocr(...)
end

.paint ⇒ Object

Generates or edits an image and returns an Image, or an array when the provider returns several images. Pass with: for source images, mask: for a mask, and count: for multiple results. See Image.paint.

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


309
310
311
 
# File 'lib/ruby_llm.rb', line 309

def paint(...)
  Image.paint(...)
end

.providers ⇒ Object

Returns the registered provider classes.

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


444
445
446
 
# File 'lib/ruby_llm.rb', line 444

def providers
  Provider.providers.values
end

.render_prompt(name, **locals) ⇒ Object

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.



425
426
427
 
# File 'lib/ruby_llm.rb', line 425

def render_prompt(name, **locals)
  Prompt.render(name, **locals)
end

.rerank ⇒ Object

Ranks documents by relevance to a query on providers with a rerank endpoint. Arguments are forwarded to Rerank.rerank.

rerank = RubyLLM.rerank("what is ruby", docs,
                      model: "voyageai/rerank-2.5-lite", provider: :openrouter)
rerank.results.first.document


379
380
381
 
# File 'lib/ruby_llm.rb', line 379

def rerank(...)
  Rerank.rerank(...)
end

.research ⇒ Object

Runs a hosted research task and returns its report as a Message. Requires explicit provider: and agent:. See ResearchJob.research.



292
293
294
 
# File 'lib/ruby_llm.rb', line 292

def research(...)
  ResearchJob.research(...)
end

.research_later ⇒ Object

Submits a hosted research task and returns a ResearchJob immediately. Requires explicit provider: and agent:. See ResearchJob.research_later.



298
299
300
 
# File 'lib/ruby_llm.rb', line 298

def research_later(...)
  ResearchJob.research_later(...)
end

.speak ⇒ Object

Synthesizes speech from text and returns a Speech. Given a block, yields SpeechChunk objects as audio arrives. Arguments are forwarded to Speech.speak.

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


343
344
345
 
# File 'lib/ruby_llm.rb', line 343

def speak(...)
  Speech.speak(...)
end

.tokenize ⇒ Object

Tokenizes plain text and returns a Tokenization with its token IDs and count. Excludes chat formatting and billable generation usage. See Tokenization.tokenize for options.



237
238
239
 
# File 'lib/ruby_llm.rb', line 237

def tokenize(...)
  Tokenization.tokenize(...)
end

.transcribe ⇒ Object

Transcribes an audio file and returns a Transcription. Arguments are forwarded to Transcription.transcribe. Given a block, the transcript streams as TranscriptionChunk objects.

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

RubyLLM.transcribe("meeting.wav", model: "gpt-4o-transcribe") do |chunk|
print chunk.delta
end


358
359
360
 
# File 'lib/ruby_llm.rb', line 358

def transcribe(...)
  Transcription.transcribe(...)
end

.upload ⇒ Object

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


389
390
391
 
# File 'lib/ruby_llm.rb', line 389

def upload(...)
  UploadedFile.upload(...)
end

.workflow(name, id: nil, metadata: nil) ⇒ Object

Runs ordinary Ruby code as a named, instrumented workflow. Every RubyLLM event emitted inside the block includes the workflow ID and name. Wrap meaningful regions with Workflow#step to add step correlation.

RubyLLM.workflow("Write article", id: "article-42") do |workflow|
notes = workflow.step("Research") { researcher.ask(topic).content }
workflow.step("Draft") { writer.ask(notes).content }
end

If id: is omitted, RubyLLM generates one. Pass metadata: to attach application data to every nested event as workflow_metadata. Workflows may nest; an inner workflow keeps its own identity and records its parent as workflow_parent_id. The block's return value is returned unchanged.



207
208
209
 
# File 'lib/ruby_llm.rb', line 207

def workflow(name, id: nil, metadata: nil, &)
  Workflow.new(name, id:, metadata:, config: config).run(&)
end