# Getting Started

Install RubyLLM and build with chats, tools, agents, images, video, audio, and document processing in Ruby and Rails.
{: .fs-6 .fw-300 }

After reading this guide, you will know:

*   How to install RubyLLM.
*   How to configure the providers you want to use.
*   How to chat, stream responses, and ask about files.
*   How to define tools, agents, and structured output.
*   How to generate images, video, and speech, and transcribe audio.
*   How to extract document text, moderate content, and search with embeddings and reranking.
*   How to track costs and save conversations in Rails.

Each example shows one feature. Try the ones your application needs, then follow its guide for more options.

## Installation

Add the RubyLLM 2.0 release candidate with Bundler:

```sh
bundle add ruby_llm --version 2.0.0.rc3
```

These guides cover the 2.0 prerelease. For an existing 1.x application, use the [stable-version docs](/v1/) or follow the [upgrade guide](/upgrading/) before switching versions.
{: .important }

## Minimal Configuration

Start with an OpenAI API key. Put this configuration at the start of your script, or in `config/initializers/ruby_llm.rb` in Rails:

```ruby
require 'ruby_llm'

RubyLLM.configure do |config|
  config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
end
```

Most examples below use OpenAI. The video, OCR, and reranking examples show the additional provider keys they need. Configure only the providers you use. See [Configuration](/configuration/) for other providers and local models.

## Your First Chat

Ask a question and read the response:

```ruby
chat = RubyLLM.chat

response = chat.ask "What is Ruby on Rails?"

puts response.content
# => "Ruby on Rails, often shortened to Rails, is a server-side web application..."
```

The chat remembers the conversation, so you can follow up:

```ruby
response = chat.ask "How do I create my first Rails app?"
puts response.content
```

See [Chatting with AI Models](/chat/) for choosing models and setting instructions.

## Streaming a Response

Pass a block to `ask` and RubyLLM yields chunks as they arrive:

```ruby
chat.ask "Tell me a story about a Ruby programmer" do |chunk|
  print chunk.content
end
```

See the [Streaming Guide](/streaming/) for streaming into web pages and background jobs.

## Asking About Files

Pass an image or PDF with `with:`:

```ruby
chat = RubyLLM.chat
response = chat.ask "Summarize this document", with: "report.pdf"
puts response.content
```

Use your own files in these examples. See [Attachments](/attachments/) for supported formats, URLs, and Active Storage files.

## Getting Structured Output

Describe the fields you want in a Ruby schema, then read the result as a Hash:

```ruby
class PersonSchema < Schematist::Schema
  string :name
  integer :age
end

response = RubyLLM.chat.with_schema(PersonSchema).ask "Alice is 30 years old."
response.parsed
# => {"name" => "Alice", "age" => 30}
```

Schematist comes with RubyLLM. See [Structured Output](/structured-output/) for nested objects, arrays, and optional fields.

## Giving the Model Tools

Let the model call your Ruby code. Define a tool and implement `execute`:

```ruby
class CurrentTime < RubyLLM::Tool
  description "Returns the current date, time, and time zone"

def execute
    Time.now.to_s
  end
end

response = RubyLLM.chat.with_tools(CurrentTime).ask "What day is it?"
puts response.content
```

RubyLLM runs the tool calls and returns their results to the model. See [Tools](/tools/) for parameters and [Tool Execution](/tool-execution/) for human approvals.

## Defining an Agent

Give an agent its model, instructions, and tools in a Ruby class. This one uses the `CurrentTime` tool above:

```ruby
class PlanningAssistant < RubyLLM::Agent
  model "gpt-5.6-luna"
  instructions "Help plan the week. Check the current date before suggesting dates."
  tools CurrentTime
end

response = PlanningAssistant.new.ask "Help me plan a three-day Ruby study schedule."
puts response.content
```

See [Agents](/agents/) for reusable prompts, inputs, and Rails persistence, or [Agentic Workflows](/agentic-workflows/) for coordinating agents.

## Generating an Image

Generate an image and save it:

```ruby
image = RubyLLM.paint "A photorealistic red panda coding Ruby"
image.save "red_panda.png"
```

See [Image Generation](/image-generation/) for editing images, choosing sizes, and generating several at once.

## Generating a Video

Generate a video and save it the same way. The default video model uses xAI, so add its key to your configuration:

```ruby
RubyLLM.configure do |config|
  config.xai_api_key = ENV.fetch('XAI_API_KEY')
end
```

```ruby
video = RubyLLM.animate "A red panda typing on a laptop, with rain at the window"
video.save "red_panda.mp4"
```

`animate` waits for the video to finish. See [Video Generation](/video-generation/) for other providers, animating an image, and submitting jobs with `animate_later`.

## Generating Speech

Turn text into an audio file:

```ruby
speech = RubyLLM.speak "Welcome to your first RubyLLM application."
speech.save "welcome.mp3"
```

See [Text to Speech](/text-to-speech/) for voices, languages, and audio formats.

## Transcribing Audio

Turn a recording into text:

```ruby
transcript = RubyLLM.transcribe "meeting.wav"
puts transcript.text
```

See [Audio Transcription](/audio-transcription/) for timestamps, speaker identification, and streaming.

## Extracting Text from Documents

Extract text from PDFs and scanned images as Markdown. OCR uses Mistral, so add its key:

```ruby
RubyLLM.configure do |config|
  config.mistral_api_key = ENV.fetch('MISTRAL_API_KEY')
end
```

```ruby
document = RubyLLM.ocr "scanned-contract.pdf"
puts document.markdown
```

See [Document OCR](/ocr/) for extracting individual pages and working with tables.

## Moderating Content

Check whether the model flags text for moderation:

```ruby
moderation = RubyLLM.moderate "I love programming in Ruby."
moderation.flagged?
# => false
```

See [Moderation](/moderation/) for categories, scores, and image moderation.

## Creating an Embedding

Turn text into a vector for similarity search:

```ruby
embedding = RubyLLM.embed "Ruby is optimized for programmer happiness."
vector = embedding.vectors
```

See [Embeddings](/embeddings/) for embedding multiple documents and [RAG](/rag/) for answering questions from your own content.

## Ranking Search Results

Order candidate documents by how well they answer a question. This example uses Cohere:

```ruby
RubyLLM.configure do |config|
  config.cohere_api_key = ENV.fetch('COHERE_API_KEY')
end
```

```ruby
documents = ["Reset your password in Settings.", "Invoices arrive by email."]
ranked = RubyLLM.rerank("How do I reset my password?", documents,
                       model: "rerank-v3.5")
puts ranked.results.first.document
```

See [Reranking](/rerank/) for scores, result limits, and combining it with embeddings.

## Tracking Usage and Costs

Read token counts and costs from the response:

```ruby
response = RubyLLM.chat.ask "Explain Ruby blocks in one paragraph."
response.tokens.input
response.tokens.output
response.cost.total
```

See [Cost and Usage Tracking](/cost-and-usage-tracking/) for cache usage, retries, and the Rails usage ledger. Use [Batches](/batches/) for bulk work that can run asynchronously.

## Using It in Rails

Use the install generator to create Chat and Message models with Active Record persistence:

```bash
bin/rails generate ruby_llm:install
bin/rails db:migrate
bin/rails ruby_llm:load_models
```

```ruby
chat = Chat.create!(model: "gpt-5.6-luna")
chat.ask "What's the best way to learn Rails?"
```

The API stays the same, and each message persists automatically. Pass Active Storage attachments with `with:`, just as you pass files in plain Ruby. Optionally, add a ready-to-use chat interface with Hotwire streaming, controllers, and an Active Job:

```bash
bin/rails generate ruby_llm:chat_ui
```

Then visit `http://localhost:3000/chats` to start chatting. See the [Rails Integration Guide](/rails/) for full details.

## What's Next?

Continue with the guide for the feature you want to build:

*   [Chatting with AI Models](/chat/)
*   [Models](/available-models/) for comparing capabilities and pricing
*   [Agents](/agents/) and [Agentic Workflows](/agentic-workflows/)
*   [Batches](/batches/) and [Prompt Caching](/prompt-caching/)
*   [Rails Integration](/rails/)
*   [AI Coding Assistants](/ai-coding-assistants/)
*   [Configuration](/configuration/)
*   [Error Handling](/error-handling/)

Getting Started

Install RubyLLM and build with chats, tools, agents, images, video, audio, and document processing in Ruby and Rails.

After reading this guide, you will know:

How to install RubyLLM.
How to configure the providers you want to use.
How to chat, stream responses, and ask about files.
How to define tools, agents, and structured output.
How to generate images, video, and speech, and transcribe audio.
How to extract document text, moderate content, and search with embeddings and reranking.
How to track costs and save conversations in Rails.

Each example shows one feature. Try the ones your application needs, then follow its guide for more options.

Installation

Add the RubyLLM 2.0 release candidate with Bundler:

bundle add ruby_llm --version 2.0.0.rc3

These guides cover the 2.0 prerelease. For an existing 1.x application, use the stable-version docs or follow the upgrade guide before switching versions.

Minimal Configuration

Start with an OpenAI API key. Put this configuration at the start of your script, or in config/initializers/ruby_llm.rb in Rails:

require 'ruby_llm'

RubyLLM.configure do |config|
  config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
end

Most examples below use OpenAI. The video, OCR, and reranking examples show the additional provider keys they need. Configure only the providers you use. See Configuration for other providers and local models.

Your First Chat

Ask a question and read the response:

chat = RubyLLM.chat

response = chat.ask "What is Ruby on Rails?"

puts response.content
# => "Ruby on Rails, often shortened to Rails, is a server-side web application..."

The chat remembers the conversation, so you can follow up:

response = chat.ask "How do I create my first Rails app?"
puts response.content

See Chatting with AI Models for choosing models and setting instructions.

Streaming a Response

Pass a block to ask and RubyLLM yields chunks as they arrive:

chat.ask "Tell me a story about a Ruby programmer" do |chunk|
  print chunk.content
end

See the Streaming Guide for streaming into web pages and background jobs.

Asking About Files

Pass an image or PDF with with::

chat = RubyLLM.chat
response = chat.ask "Summarize this document", with: "report.pdf"
puts response.content

Use your own files in these examples. See Attachments for supported formats, URLs, and Active Storage files.

Getting Structured Output

Describe the fields you want in a Ruby schema, then read the result as a Hash:

class PersonSchema < Schematist::Schema
  string :name
  integer :age
end

response = RubyLLM.chat.with_schema(PersonSchema).ask "Alice is 30 years old."
response.parsed
# => {"name" => "Alice", "age" => 30}

Schematist comes with RubyLLM. See Structured Output for nested objects, arrays, and optional fields.

Giving the Model Tools

Let the model call your Ruby code. Define a tool and implement execute:

class CurrentTime < RubyLLM::Tool
  description "Returns the current date, time, and time zone"

  def execute
    Time.now.to_s
  end
end

response = RubyLLM.chat.with_tools(CurrentTime).ask "What day is it?"
puts response.content

RubyLLM runs the tool calls and returns their results to the model. See Tools for parameters and Tool Execution for human approvals.

Defining an Agent

Give an agent its model, instructions, and tools in a Ruby class. This one uses the CurrentTime tool above:

class PlanningAssistant < RubyLLM::Agent
  model "gpt-5.6-luna"
  instructions "Help plan the week. Check the current date before suggesting dates."
  tools CurrentTime
end

response = PlanningAssistant.new.ask "Help me plan a three-day Ruby study schedule."
puts response.content

See Agents for reusable prompts, inputs, and Rails persistence, or Agentic Workflows for coordinating agents.

Generating an Image

Generate an image and save it:

image = RubyLLM.paint "A photorealistic red panda coding Ruby"
image.save "red_panda.png"

See Image Generation for editing images, choosing sizes, and generating several at once.

Generating a Video

Generate a video and save it the same way. The default video model uses xAI, so add its key to your configuration:

RubyLLM.configure do |config|
  config.xai_api_key = ENV.fetch('XAI_API_KEY')
end

video = RubyLLM.animate "A red panda typing on a laptop, with rain at the window"
video.save "red_panda.mp4"

animate waits for the video to finish. See Video Generation for other providers, animating an image, and submitting jobs with animate_later.

Generating Speech

Turn text into an audio file:

speech = RubyLLM.speak "Welcome to your first RubyLLM application."
speech.save "welcome.mp3"

See Text to Speech for voices, languages, and audio formats.

Transcribing Audio

Turn a recording into text:

transcript = RubyLLM.transcribe "meeting.wav"
puts transcript.text

See Audio Transcription for timestamps, speaker identification, and streaming.

Extracting Text from Documents

Extract text from PDFs and scanned images as Markdown. OCR uses Mistral, so add its key:

RubyLLM.configure do |config|
  config.mistral_api_key = ENV.fetch('MISTRAL_API_KEY')
end

document = RubyLLM.ocr "scanned-contract.pdf"
puts document.markdown

See Document OCR for extracting individual pages and working with tables.

Moderating Content

Check whether the model flags text for moderation:

moderation = RubyLLM.moderate "I love programming in Ruby."
moderation.flagged?
# => false

See Moderation for categories, scores, and image moderation.

Creating an Embedding

Turn text into a vector for similarity search:

embedding = RubyLLM.embed "Ruby is optimized for programmer happiness."
vector = embedding.vectors

See Embeddings for embedding multiple documents and RAG for answering questions from your own content.

Ranking Search Results

Order candidate documents by how well they answer a question. This example uses Cohere:

RubyLLM.configure do |config|
  config.cohere_api_key = ENV.fetch('COHERE_API_KEY')
end

documents = ["Reset your password in Settings.", "Invoices arrive by email."]
ranked = RubyLLM.rerank("How do I reset my password?", documents,
                       model: "rerank-v3.5")
puts ranked.results.first.document

See Reranking for scores, result limits, and combining it with embeddings.

Tracking Usage and Costs

Read token counts and costs from the response:

response = RubyLLM.chat.ask "Explain Ruby blocks in one paragraph."
response.tokens.input
response.tokens.output
response.cost.total

See Cost and Usage Tracking for cache usage, retries, and the Rails usage ledger. Use Batches for bulk work that can run asynchronously.

Using It in Rails

Use the install generator to create Chat and Message models with Active Record persistence:

bin/rails generate ruby_llm:install
bin/rails db:migrate
bin/rails ruby_llm:load_models

chat = Chat.create!(model: "gpt-5.6-luna")
chat.ask "What's the best way to learn Rails?"

The API stays the same, and each message persists automatically. Pass Active Storage attachments with with:, just as you pass files in plain Ruby. Optionally, add a ready-to-use chat interface with Hotwire streaming, controllers, and an Active Job:

bin/rails generate ruby_llm:chat_ui

Then visit http://localhost:3000/chats to start chatting. See the Rails Integration Guide for full details.

What’s Next?

Continue with the guide for the feature you want to build:

Chatting with AI Models
Models for comparing capabilities and pricing
Agents and Agentic Workflows
Batches and Prompt Caching
Rails Integration
AI Coding Assistants
Configuration
Error Handling