# 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 https://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.

# Class methods:

    batch
    chat
    config
    configure
    context
    download
    embed
    models
    moderate
    paint
    providers
    render_prompt
    speak
    transcribe
    upload

# RubyLLM::batch
---
    batch(chats)

---

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)

# RubyLLM::chat
---
    chat(...)

---

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')

# RubyLLM::config
---
    config()

---

Returns the global Configuration instance.

# RubyLLM::configure
---
    configure() { |config| ... }

---

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

# RubyLLM::context
---
    context() { |context_config| ... }

---

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"

# RubyLLM::download
---
    download(...)

---

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

    content = RubyLLM.download(file.id)

# RubyLLM::embed
---
    embed(...)

---

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

# RubyLLM::models
---
    models()

---

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

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

# RubyLLM::moderate
---
    moderate(...)

---

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

# RubyLLM::paint
---
    paint(...)

---

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")

# RubyLLM::providers
---
    providers()

---

Returns the registered provider classes.

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

# RubyLLM::render_prompt
---
    render_prompt(name, **locals)

---

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.

# RubyLLM::speak
---
    speak(...)

---

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")

# RubyLLM::transcribe
---
    transcribe(...)

---

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

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

# RubyLLM::upload
---
    upload(...)

---

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