RubyLLM

https://rubyllm.com/
Admin
RubyLLM is a unified Ruby API for integrating multiple AI providers like GPT, Claude, and Gemini,...
Tokens:551,281
Snippets:5,513
Trust Score:7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Setup Chat and Message Models with acts_as_chat and acts_as_message

Source: https://rubyllm.com/api/RubyLLM/ActiveRecord/ActsAs.html

Shows the full setup for a persisted RubyLLM chat: a Chat model using acts_as_chat, a Message model using acts_as_message with an attached file, and a usage example that creates a chat and asks a question. The install generator creates the required schema; the chat_ui generator adds controllers, an Active Job, and Turbo Stream views.

```ruby
class Chat < ApplicationRecord
  acts_as_chat
end

class Message < ApplicationRecord
  acts_as_message
  has_many_attached :attachments
end

chat = Chat.create!(model: "gpt-5.6-luna")
response = chat.ask "Summarize this report.", with: report.document
response.content
chat.cost.total

```

--------------------------------

### Install ActiveStorage manually

Source: https://rubyllm.com/rails-generators

Run these commands to manually install ActiveStorage and run migrations if you skipped the generator's automatic setup.

```bash
bin/rails active_storage:install
bin/rails db:migrate

```

--------------------------------

### suggest method usage example

Source: https://rubyllm.com/api/RubyLLM/MCP/Prompt.html

Example of calling suggest on a prompt to get suggested values for an argument.

```ruby
github.prompts.first.suggest(language: "ru")  # => ["ruby", "rust"]
```

--------------------------------

### resource usage examples

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Examples of reading a resource directly and using a template with variables.

```ruby
files.resource("file:///project/README.md")
files.resource("file:///{path}", path: "Gemfile")

```

--------------------------------

### temperature usage example

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Example of setting the temperature to 0.2.

```ruby
temperature 0.2
```

--------------------------------

### provider_tools usage examples

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Examples of enabling provider-executed tools, including with options.

```ruby
provider_tools :web_search
```

```ruby
provider_tools web_search: { allowed_domains: ["ruby-lang.org"] }
```

--------------------------------

### sync_instructions usage example

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Example of syncing instructions for a chat record.

```ruby
WorkAssistant.sync_instructions(chat)
```

--------------------------------

### tools usage examples

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Example calls to tools showing how to declare tools with a list or with a block that defers construction.

```ruby
tools SearchDocs, LookupAccount
tools { [TodoTool.new(chat: chat)] }
```

--------------------------------

### suggest method usage example

Source: https://rubyllm.com/api/RubyLLM/MCP/ResourceTemplate.html

Example call to suggest with a partial path, returning an array of suggested values.

```ruby
template.suggest(path: "app/mo")  # => ["app/models/"]
```

--------------------------------

### Describe a stdio MCP server with command and directory

Source: https://rubyllm.com/mcp

Give the command that starts a local server; RubyLLM talks to it over stdio. The process starts on the first request and stops when you call close.

```ruby
class Files < RubyLLM::MCP
  command "npx", "-y", "@modelcontextprotocol/server-filesystem", "."
  directory Rails.root
  env NODE_ENV: "production"
end
```

--------------------------------

### listen usage example

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Example usage of the listen method with resources and tasks.

```ruby
handbook = Handbook.new.listen(resources: ["handbook://policies"])
reports.listen(tasks: chat.pending_tasks)

```

--------------------------------

### schema usage examples

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Examples of setting a structured output schema with a class and with a block.

```ruby
schema PersonSchema
```

```ruby
schema do
  string :verdict, enum: ["pass", "revise"]
  string :feedback
end
```

--------------------------------

### command usage example

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Shows how to set the command for a stdio server.

```ruby
command "npx", "-y", "@modelcontextprotocol/server-filesystem", "."

```

--------------------------------

### directory usage example

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Shows how to set the working directory for a stdio server.

```ruby
directory Rails.root

```

--------------------------------

### Run migrations and load models after install

Source: https://rubyllm.com/rails-generators

After running the install generator, migrate the database and load RubyLLM models to enable Chat.create! and chat.ask.

```bash
bin/rails db:migrate
```

```bash
bin/rails ruby_llm:load_models
```

--------------------------------

### configure

Source: https://rubyllm.com/api/index.html

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

```APIDOC
## RubyLLM.configure

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

### Method
configure

### Endpoint
RubyLLM.configure() { |config| ... }

### Parameters
- **block** - The block that receives the global configuration.

### Example
```ruby
RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
end
```

```

--------------------------------

### Install RubyLLM and generate chat UI

Source: https://rubyllm.com/

Install RubyLLM 2.1.0, run the install generator, migrate the database, generate a chat UI, and start the Rails server. The generator creates the chat model, message model, chats controller, show view, and chat response job.

```shell
$ bundle add ruby_llm --version 2.1.0
$ bin/rails generate ruby_llm:install
$ bin/rails db:migrate
$ bin/rails generate ruby_llm:chat_ui

create  app/models/chat.rb
create  app/models/message.rb
create  app/controllers/chats_controller.rb
create  app/views/chats/show.html.erb
create  app/jobs/chat_response_job.rb

$ bin/rails server
=> Booting Puma
=> Rails application starting on http://localhost:3000
~ 

```

--------------------------------

### defer usage examples

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Shows how to defer specific tools or all tools of the server.

```ruby
defer :search_code, :list_workflows
defer

```

--------------------------------

### provider_options usage example

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Example of setting provider options with a service tier.

```ruby
provider_options service_tier: "flex"
```

--------------------------------

### Create a partial file _tone.txt.erb

Source: https://rubyllm.com/prompt-rendering

A partial is a prompt file whose name starts with an underscore. This example creates `app/prompts/work_assistant/_tone.txt.erb` with ERB content that uses the `display_name` local.

```erb
Be warm and direct with <%= display_name %>.

```

--------------------------------

### Run the install generator

Source: https://rubyllm.com/rails-generators

Generates migrations, models, initializer, and directories for RubyLLM. Run this first to set up persistence.

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

--------------------------------

### prompt usage example

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Example of using the prompt method with a chat.

```ruby
chat.ask github.prompt(:code_review, code: diff)

```

--------------------------------

### Install RubyLLM in Rails with the install generator

Source: https://rubyllm.com/getting-started

Runs the install generator to create Chat and Message models with Active Record persistence, then migrates the database and loads the models.

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

--------------------------------

### Run migrations and load models after install

Source: https://rubyllm.com/rails-generators

After running the install generator, run these commands to apply migrations and load the RubyLLM models. Then you can create a persisted chat with `Chat.create!` and send a message with `chat.ask`.

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

```

--------------------------------

### Install RubyLLM skill from gem

Source: https://rubyllm.com/ai-coding-assistants

Installs the RubyLLM skill from the gem version in your bundle. The installer prompts for your coding assistant and installation scope. Run from your application directory.

```bash
npx skills add "$(bundle show ruby_llm)" --skill rubyllm
```

--------------------------------

### Define an MCP subclass with a local command

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Shows how to start a local server that speaks over stdio using a command.

```ruby
class Files < RubyLLM::MCP
  command "npx", "-y", "@modelcontextprotocol/server-filesystem", "."
end

```

--------------------------------

### chat usage examples

Source: https://rubyllm.com/api

Examples of creating a chat with default model and with a specific model.

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

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

--------------------------------

### Turn#to_s example output

Source: https://rubyllm.com/api/RubyLLM/RequestShape/Turn.html

Example output of to_s for a turn with a model role and multiple parts.

```ruby
turn.to_s # => "#3 model: thinking (11 chars), text (13 chars), signed"

```

--------------------------------

### Part#to_s example output

Source: https://rubyllm.com/api/RubyLLM/RequestShape/Part.html

Example output of Part#to_s for various part kinds: text, image, document, tool result, and thinking with a signature.

```ruby
text (13 chars)
image/png (34512 bytes)
document (url)
result find_tasks (6859 chars)
thinking (no text), signed

```

--------------------------------

### Example to_s output

Source: https://rubyllm.com/api/RubyLLM/RequestShape.html

Example output of RequestShape#to_s, showing the format for a conversation with a tool call and a thinking part problem.

```text
gemini, gemini-2.5-flash, model call 1 of the turn
payload keys: contents, generationConfig, tools
thinking: includeThoughts true, thinkingBudget -1
#0 user: text (17 chars)
#1 model: call find_tasks (args 40 chars), signed
#2 user: result find_tasks (6859 chars)
#3 model: thinking (no text), signed, text (1075 chars)
#4 user: text (31 chars)
tools: find_tasks
tool round at #1: 1 call, 1 result, paired
problem at #3, part 0: thinking part carries no data

```

--------------------------------

### with_instructions usage examples

Source: https://rubyllm.com/api/RubyLLM/ActiveRecord/ChatMethods.html

Example usage of with_instructions: sets system instructions, appends to existing ones, or applies only to the in-memory chat without persisting.

```ruby
chat.with_instructions "You are a Ruby expert."
chat.with_instructions "Use short bullet points.", append: true
chat.with_instructions current_context, persist: false
```

--------------------------------

### RubyLLM.ocr usage examples

Source: https://rubyllm.com/api/RubyLLM/OCR.html

Examples of calling RubyLLM.ocr with a local file, a URL, and with pages and provider_options arguments.

```ruby
RubyLLM.ocr("report.pdf")
RubyLLM.ocr("https://example.com/scan.png")
RubyLLM.ocr("report.pdf", pages: [0, 1], provider_options: { table_format: "html" })

```

--------------------------------

### step usage example

Source: https://rubyllm.com/api/RubyLLM/ActiveRecord/ChatMethods.html

Example usage of the step method to advance the chat until it is complete or waiting.

```ruby
chat.step until chat.complete? || chat.waiting?

```

--------------------------------

### model_id example

Source: https://rubyllm.com/api/RubyLLM/ActiveRecord/ChatMethods.html

Example of calling model_id and its return value.

```ruby
chat.model_id # => "gpt-5.6-luna"
```

--------------------------------

### name usage example

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Example showing the name method returns the default name.

```ruby
GoogleDrive.new.name # => "google_drive"

```

--------------------------------

### Example: judge with questions and with images

Source: https://rubyllm.com/api/RubyLLM/Judge.html

Shows two usage examples: one passing input and a probability question, and another passing an image via with: and omitting input.

```ruby
RubyLLM.judge("Please help today",
  questions: { urgent: { type: :probability, instructions: "Is this urgent?" } })
Receipt.judge(with: "receipt.png")
```

--------------------------------

### compaction usage examples

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Usage examples for the compaction class method: enable with defaults, disable, or pass compaction options.

```ruby
compaction
compaction false
compaction at: 50_000

```

--------------------------------

### Install RubyLLM skill from repository

Source: https://rubyllm.com/ai-coding-assistants

Installs the RubyLLM skill from the repository. This version follows RubyLLM development; prefer the gem-packaged skill for applications pinned to a released version.

```bash
npx skills add crmne/ruby_llm --skill rubyllm
```

--------------------------------

### command

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Sets or returns the command that starts a local server speaking over stdio.

```APIDOC
## command

### Description
Sets the command that starts a local server speaking over stdio. The process starts on the first request. Called with no arguments, returns the configured command.

### Method
Class method

### Signature
`command(*argv)`

### Parameters
- **argv** (Array<String>) - Optional - The command and its arguments.

### Returns
- The configured command when called with no arguments.

### Example
```ruby
command "npx", "-y", "@modelcontextprotocol/server-filesystem", "."
```
```

--------------------------------

### Conventional directory structure

Source: https://rubyllm.com/rails-generators

The install generator creates these directories with .gitkeep files. Agents, tools, and schemas can live anywhere in autoload paths.

```text
app/
|-- agents/
|-- prompts/
|-- schemas/
`-- tools/
```

--------------------------------

### OCR a PDF and get markdown

Source: https://rubyllm.com/api/index.html

Example of extracting text from a PDF and accessing the markdown output.

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

```

--------------------------------

### Get the total cost of a response

Source: https://rubyllm.com/api/RubyLLM/Message.html

Usage example for the cost method, accessing the total cost of a response.

```ruby
response.cost.total

```

--------------------------------

### Upgrade generator for credential storage

Source: https://rubyllm.com/mcp

Add the ruby_llm_mcp_credentials table to an existing Rails app that installed RubyLLM 2.0. New applications get the table from ruby_llm:install. Run db:encryption:init only if your app has no encryption keys yet.

```bash
bin/rails generate ruby_llm:upgrade
bin/rails db:encryption:init # if your app has no encryption keys yet
bin/rails db:migrate
```

--------------------------------

### cost method with usage example

Source: https://rubyllm.com/api/RubyLLM/VideoJob.html

Returns the Cost the provider reported for the job. Its total is nil while the job is pending or when the provider reports no price. The example shows waiting for the job and reading the total cost.

```ruby
# File lib/ruby_llm/video_job.rb, line 139
def cost
  Cost.new(tokens: Tokens.new(reported_cost: @reported_cost))
end
```

```ruby
job.wait
job.cost.total # => 0.05

```

--------------------------------

### thinking usage examples

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Example calls to the thinking method showing how to enable thinking with no options, disable it, or pass effort, budget, and display options.

```ruby
thinking
thinking false
thinking effort: :low
thinking budget: 10_000
thinking display: :summarized
```

--------------------------------

### Render a support prompt with RubyLLM.render_prompt

Source: https://rubyllm.com/prompt-rendering

Create a support prompt template in app/prompts/support/instructions.txt.erb and render it with RubyLLM.render_prompt, passing product_name and customer_name as locals. The rendered string is then attached to a chat with with_instructions before asking a question.

```erb
You are a support assistant for <%= product_name %>.
The current customer is <%= customer_name %>.
Answer with concise, practical steps.

```

```ruby
instructions = RubyLLM.render_prompt(
  "support/instructions",
  product_name: "BillingHub",
  customer_name: current_user.name
)
chat = RubyLLM.chat
chat.with_instructions(instructions)
chat.ask("How do I update my invoice email?")

```

--------------------------------

### Install RubyLLM 2.1 with Bundler

Source: https://rubyllm.com/getting-started

Adds RubyLLM 2.1.0 to your Gemfile using Bundler. For existing 1.x applications, consult the upgrade guide before switching versions.

```sh
bundle add ruby_llm --version 2.1.0
```

--------------------------------

### Configure timeouts for high-latency connections

Source: https://rubyllm.com/configuration-connection

Example for high-latency connections: increases timeout to 300 seconds, max_retries to 5, starts with a 1-second delay, and uses a less aggressive backoff factor of 1.5.

```ruby
RubyLLM.configure do |config|
  config.request_timeout = 300        # 5 minutes for complex tasks
  config.max_retries = 5              # More retry attempts
  config.retry_interval = 1.0         # Start with 1 second delay
  config.retry_backoff_factor = 1.5   # Less aggressive backoff
end
```

--------------------------------

### tools with defer option

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Example call to tools passing defer: as Chat#with_tools takes it.

```ruby
tools SearchDocs, LookupAccount, defer: true
```

--------------------------------

### Persist citations with ActiveRecord acts_as_chat

Source: https://rubyllm.com/citations

Persists citations as JSON on the message table when using acts_as_chat and acts_as_message. New installs generate the migration automatically; apps upgrading from 1.16 must add the column via the 2.0 upgrade guide.

```ruby
# Migration (generated automatically with new installs)
# t.json :citations
chat_record = Chat.create!(model: 'claude-sonnet-5')
chat_record.with_citations
response = chat_record.ask "Who created Ruby?", with: "facts.txt"
chat_record.messages.last.citations # => [RubyLLM::Citation, ...]
```

--------------------------------

### DatabaseSearch - Custom Initialization for Tools

Source: https://rubyllm.com/tool-parameters

Creates a tool with custom initialization to hold dependencies and runtime state. The example instantiates DatabaseSearch with a database object and passes it to with_tools. Define separate tool classes when tools need different names, descriptions, or inputs.

```ruby
class DatabaseSearch < RubyLLM::Tool
  description "Searches documents by relevance"
  parameter :query, description: "The search query"
  parameter :limit, type: :integer, description: "Maximum number of results", required: false

  def initialize(database)
    @database = database
  end

  def execute(query:, limit: 5)
    @database.search(query, limit: limit)
  end
end

search_tool = DatabaseSearch.new(MyDatabase)
chat.with_tools(search_tool)
```

--------------------------------

### Enable and read citations with acts_as_chat

Source: https://rubyllm.com/citations

Shows how to enable citations on a chat record and retrieve them from the last message. Requires the `citations` JSON column on the messages table, which is generated automatically for new installs; apps upgrading from 1.16 get it from the 2.0 upgrade.

```ruby
# Migration (generated automatically with new installs)
# t.json :citations

chat_record = Chat.create!(model: 'claude-sonnet-5')
chat_record.with_citations
response = chat_record.ask "Who created Ruby?", with: "facts.txt"

chat_record.messages.last.citations # => [RubyLLM::Citation, ...]

```

--------------------------------

### Start background listener with listen

Source: https://rubyllm.com/mcp

Start listening for changes in the background. listen asks the server for updates to the given resources (as URIs or resources) and tasks, and returns once the server confirms. It runs in its own thread until close is called. Raises RubyLLM::MCP::Error if the server cannot be reached or refuses updates.

```ruby
handbook = Handbook.new.listen(resources: ["handbook://policies"])
```

--------------------------------

### Access raw response body with response.raw

Source: https://rubyllm.com/chat

Use `response.raw` to get the raw Faraday::Response object from a chat answer. The example prints the response body. The raw response does not keep the request it answered, so long conversations do not hold copies of every request.

```ruby
response = chat.ask("What is the capital of France?")
puts response.raw.body

```

--------------------------------

### Using a ResourceTemplate to suggest and access resources

Source: https://rubyllm.com/api/RubyLLM/MCP/ResourceTemplate.html

Shows how to get the first resource template from a files MCP server, inspect its URI, suggest a path completion, and access a resource using the template URI.

```ruby
template = files.resource_templates.first
template.uri                        # => "file:///{path}"
template.suggest(path: "app/mo")    # => ["app/models/"]
files.resource(template.uri, path: "Gemfile")
```

--------------------------------

### List and filter models with RubyLLM.models

Source: https://rubyllm.com/models

Use RubyLLM.models.all to get all models, chat_models and embedding_models for type-specific lists, by_provider to filter by provider, by_family to filter by family, and chain filters with Enumerable methods like select. The example shows filtering for OpenAI vision models and printing the count.

```ruby
all_models = RubyLLM.models.all

chat_models = RubyLLM.models.chat_models
embedding_models = RubyLLM.models.embedding_models

openai_models = RubyLLM.models.by_provider(:openai) # or 'openai'

# Filter by model family (e.g., all Claude Sonnet variants)
claude_sonnet_family = RubyLLM.models.by_family('claude-sonnet')

# Chain filters and use Enumerable methods
openai_vision_models = RubyLLM.models.by_provider(:openai)
                                   .select { |model| model.supports?(:vision) }

puts "Found #{openai_vision_models.count} OpenAI vision models."
```

--------------------------------

### after_tool_progress usage example

Source: https://rubyllm.com/api/RubyLLM/Chat.html

Registers a callback that receives the ToolCall and a Progress each time a running local tool reports what it is doing. The callback runs in the thread or fiber that reports, before the tool's result. On Ruby 3.2 and later, that includes threads and fibers the tool starts. With concurrent tool execution, callbacks for different tool calls can run at the same time.

```ruby
chat.after_tool_progress do |tool_call, progress|
  puts "#{tool_call.name}: #{progress.message}"
end
```

--------------------------------

### Configure tool with as, description, fixed_arguments, and wrap options

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Shows how to shape a server tool or add one of your own. `as:` renames the tool, `description:` rewrites what the model reads, `fixed_arguments:` removes arguments from the model's view and always sends your values (which may be lambdas), and `wrap:` names a method that receives the server's Result and the call's arguments and returns what the model sees.

```ruby
tool :search_files, as: :drive_search, description: "Search the user's Drive"
tool :search_issues, fixed_arguments: { owner: "crmne", repo: "ruby_llm" }
tool :read_file, wrap: :extract_text

```

--------------------------------

### Map provider slugs with RubyLLM.providers

Source: https://rubyllm.com/api/index.html

Example of mapping provider classes to their slugs, showing the expected output format.

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

```

--------------------------------

### Get model prices

Source: https://rubyllm.com/api/RubyLLM/Model.html

Shows how to retrieve input and output prices for a model.

```ruby
model.price(:input)   # => 2.5
model.price(:output)  # => 10.0

```

--------------------------------

### bearer_token usage examples

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Shows how to set the bearer token with a value or a block.

```ruby
bearer_token ENV.fetch("LINEAR_API_KEY")
bearer_token { user.linear_token }

```

--------------------------------

### listen

Source: https://rubyllm.com/mcp

Starts background listening for server changes, subscribing to resources and tasks.

```APIDOC
## [RubyLLM::MCP] listen

### Description
Starts listening for changes in the background. It subscribes to server-announced lists, resources, and tasks, and returns once the server confirms. It listens in a separate thread until `close` is called.

### Method
`listen`

### Parameters
- **resources** (Array<String or RubyLLM::MCP::Resource>) - Optional - URIs or resources to listen for updates.
- **tasks** (Array<RubyLLM::MCP::Task>) - Optional - Tasks whose status changes to listen for.

### Returns
- The MCP instance (self) with the listener started.

### Raises
- `RubyLLM::MCP::Error` - If the server cannot be reached or will not send updates for a resource or task.

### Example
```ruby
handbook = Handbook.new.listen(resources: ["handbook://policies"])
```

### Notes
- Callbacks run in the listener's thread, one at a time.
- If the connection drops, RubyLLM resubscribes with exponential backoff (starting ~1 second, doubling up to a minute).
- Calling `listen` again replaces the resources and tasks it listens to.
```

--------------------------------

### Ask about a file with with:

Source: https://rubyllm.com/getting-started

Asks about a file by passing it with the with: option. Supports images and PDFs; use your own files in these examples.

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

--------------------------------

### with_instructions(instructions, append: false, cache_until_here: false)

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Delegates to Chat#with_instructions.

```APIDOC
## with_instructions(instructions, append: false, cache_until_here: false)

### Description
Delegates to `Chat#with_instructions`. See that method for arguments and return values.

### Method
with_instructions

### Endpoint
with_instructions

### Parameters
#### Path Parameters
- **instructions** (String) - Required - The instructions to set.
- **append** (Boolean, optional) - Optional - Whether to append to existing instructions. Defaults to false.
- **cache_until_here** (Boolean, optional) - Optional - Whether to cache until this point. Defaults to false.

### Response
Returns the chat with the given instructions.
```

--------------------------------

### Compaction Options with at, instructions, and pause_after

Source: https://rubyllm.com/chat-request-control

Provider-neutral options: at: sets the input-token threshold, instructions: guides the summary, pause_after: stops the turn after compaction. Support varies by provider; Anthropic and Bedrock Mantle support all three with a minimum threshold of 50,000 tokens, OpenAI and Azure Responses support at:, OpenRouter ignores these options.

```ruby
chat.with_compaction(at: 50_000)
chat.with_compaction(at: 100_000, instructions: "Keep every decision and open question.")
chat.with_compaction(at: 50_000, pause_after: true)
chat.with_compaction(false)
```

--------------------------------

### instructions

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Returns the instructions the server gives for using it, or nil.

```APIDOC
## instructions

### Description
Returns the instructions the server gives for using it, or `nil`.

### Method
instructions

### Signature
`instructions ()`

### Returns
- **String** - The server's instructions, or `nil` if not provided.

### Source
```ruby
# File lib/ruby_llm/mcp.rb, line 689
def instructions
  client.server['instructions']
end
```
```

--------------------------------

### Configure RubyLLM with an API key

Source: https://rubyllm.com/api/RubyLLM.html

Configures RubyLLM with an OpenAI API key from the environment. This block-style setup should be called once at startup.

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

--------------------------------

### Custom Initialization

Source: https://rubyllm.com/tool-parameters

Shows how to define a tool class with custom initialization to accept dependencies like a database object, and use it with the chat.

```APIDOC
## Custom Initialization

### Description
Defines a tool class with custom initialization to accept a database dependency, then instantiates and uses it with the chat.

### Method
initialize

### Parameters
#### Constructor Parameters
- **database** (Object) - Required - The database object used for searching.

### Example
```ruby
class DatabaseSearch < RubyLLM::Tool
  description "Searches documents by relevance"

  parameter :query,
    description: "The search query"

  parameter :limit,
    type: :integer,
    description: "Maximum number of results",
    required: false

  def initialize(database)
    @database = database
  end

  def execute(query:, limit: 5)
    @database.search(query, limit: limit)
  end
end

search_tool = DatabaseSearch.new(MyDatabase)
chat.with_tools(search_tool)
```
```

--------------------------------

### evaluates method implementation

Source: https://rubyllm.com/api/RubyLLM/Evaluation/RSpec.html

Defines one example per case, using the same runner and failure report as Evaluation.run.

```ruby
def evaluates(evaluation, dataset: nil, only: nil, **options)
  evaluation.cases(dataset:, only:).each do |test_case|
    it("#{evaluation.name}: #{test_case.name}") do
      report = evaluation.run(dataset: [test_case], **options)
      expect(report).to be_passed, report.to_s
    end
  end
end

```

--------------------------------

### Configure RubyLLM and ask a chat question

Source: https://rubyllm.com/api/RubyLLM.html

Sets the OpenAI API key from the environment and creates a chat client. Use `RubyLLM.chat` to start a conversation and `Chat#ask` to send a prompt.

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

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

```

--------------------------------

### tool_options usage example

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Example call to tool_options with choice: :required and calls: :one.

```ruby
tool_options choice: :required, calls: :one
```

--------------------------------

### Part#initialize

Source: https://rubyllm.com/api/RubyLLM/RequestShape/Part.html

Constructor for a Part. Only kind is required; size defaults to characters unless unit is :bytes, and signed: true marks a thinking signature.

```ruby
# File lib/ruby_llm/request_shape/part.rb, line 54
def initialize(kind:, size: nil, unit: nil, name: nil, source: nil, mime_type: nil, signed: false)
  @kind = kind
  @size = size
  @unit = size && (unit || :chars)
  @name = name
  @source = source
  @mime_type = mime_type
  @signed = signed
end

```

--------------------------------

### with_model usage example

Source: https://rubyllm.com/api/RubyLLM/ActiveRecord/ChatMethods.html

Example usage of with_model to switch the chat to a specific model.

```ruby
chat.with_model 'claude-sonnet-5'
```

--------------------------------

### Choose which MCP tools to expose with only

Source: https://rubyllm.com/mcp

Keep only the tools you need with `only`, or hide some with `except`. This example exposes only `search_issues`, `get_issue`, and `create_issue` from the GitHub Copilot MCP server.

```ruby
class GitHub < RubyLLM::MCP
  url "https://api.githubcopilot.com/mcp/"
  bearer_token ENV.fetch("GITHUB_TOKEN")
  only :search_issues, :get_issue, :create_issue
end
```

--------------------------------

### new

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Creates an MCP instance.

```APIDOC
## new

### Description
Creates an `MCP`. Keywords are the values of the declared `::inputs`. Pass a `Context` as `context:` to connect with its configuration: its `faraday_adapter`, `http_proxy`, and `request_timeout` apply to the server's requests and to its OAuth requests.

### Method
Constructor

### Signature
`new(context: nil, **inputs)`

### Parameters
- **context** (Context) - Optional - A `Context` object to use for connection configuration.
- **inputs** (Hash) - Optional - Values for the declared inputs.

### Examples
```ruby
Linear.new(user: current_user)
Linear.new(user: current_user, context: RubyLLM.context { |config| config.http_proxy = proxy })
```

### Errors
- Raises `ArgumentError` for unknown input names.

```

--------------------------------

### tokens usage example

Source: https://rubyllm.com/api/RubyLLM/ActiveRecord/ChatMethods.html

Example usage of the tokens method to access the input token count.

```ruby
chat.tokens.input

```

--------------------------------

### instructions

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Adds system instructions for chats this agent builds. Accepts a string, a block evaluated when the chat is built, or keyword locals for the agent's conventional prompt template. Multiple declarations are applied in order.

```APIDOC
## instructions

### Description
Adds system instructions for chats this agent builds. Accepts a string, a block evaluated when the chat is built, or keyword locals for the agent's conventional prompt template. Multiple declarations are applied in order.

### Method
instructions

### Signature
```ruby
instructions(text = nil, append: false, persist: true, cache_until_here: false, **prompt_locals, &block)
```

### Parameters
- **text** (String, optional) - The instruction text to add.
- **append** (Boolean, optional, default: false) - Whether to append to existing instructions.
- **persist** (Boolean, optional, default: true) - Whether the declaration persists in Rails mode when the record is created.
- **cache_until_here** (Boolean, optional, default: false) - Whether to cache until this point.
- **prompt_locals** (Hash, optional) - Keyword locals for the agent's conventional prompt template.
- **&block** (Block) - Optional block evaluated when the chat is built.

### Examples
```ruby
instructions "You are a helpful assistant."
instructions { "You are helping #{workspace.name}" }
instructions display_name: -> { chat.user.display_name_or_email }
instructions append: true, persist: false do
  "Today is #{Date.current}"
end
```

### Notes
- Multiple declarations are applied in order.
- The class's own declarations take precedence over its conventional template.
- Inherited declarations are used only when neither exists.
- In Rails mode, declarations persist when the record is created unless `persist: false`; `::find` always reapplies them without rewriting history.
- Called with no arguments, returns the declarations.
```

--------------------------------

### Render prompt template and use with chat

Source: https://rubyllm.com/api/index.html

Example of rendering a prompt template with locals and passing the result to a chat's instructions.

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

```

--------------------------------

### headers override example

Source: https://rubyllm.com/api/RubyLLM/Provider.html

Example override that adds an Authorization header using the configured API key.

```ruby
def headers
  { 'Authorization' => "Bearer #{@config.acme_api_key}" }
end
```

--------------------------------

### Explore an MCP server's tools and instructions in a console

Source: https://rubyllm.com/mcp

Explore a server in a console: list its tools, inspect a tool's description, and get the server's instructions. The `=>` lines show the expected output.

```ruby
>> docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
>> docs.tools
=> [#<RubyLLM::MCP::Tool name: "microsoft_docs_search", read_only: true>, ...]
>> docs.tools.first.description
=> "Search official Microsoft/Azure documentation..."
>> docs.instructions
=> "..."
```

--------------------------------

### Create a runtime MCP server with a name and prefix

Source: https://rubyllm.com/mcp

Use RubyLLM.mcp for servers users add at runtime. A server with a transport also needs a name, since it has no URL or command to be named after.

```ruby
RubyLLM.mcp(url: server.endpoint, name: "mcp_#{server.id}", prefix: "mcp_#{server.id}",
            oauth: { owner: server })
```

--------------------------------

### Install RubyLLM 2.1

Source: https://rubyllm.com/whats-new-in-2-1

Install RubyLLM 2.1.0 or later compatible version. Requires Ruby 3.2 or later.

```sh
bundle add ruby_llm --version "~> 2.1.0"

```

--------------------------------

### Create, find, and sync Rails-backed agent

Source: https://rubyllm.com/agents

Shows how to create, find, and sync instructions for a Rails-backed agent. create/create! and find require chat_model; calling them without it raises an error. create persists instructions, find applies them at runtime only, and sync_instructions explicitly persists them.

```ruby
chat = WorkAssistant.create!(user: current_user)

chat = WorkAssistant.find(params[:id])

WorkAssistant.sync_instructions(chat)
```

--------------------------------

### citations usage examples

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Usage examples for the citations class method: enable with default true or disable with false.

```ruby
citations
citations false

```

--------------------------------

### Set and manage system prompts with with_instructions

Source: https://rubyllm.com/chat

Shows how to set, replace, append, and clear system instructions using with_instructions. By default, with_instructions replaces the active instruction; pass append: true to add another, or nil to clear. Instructions are :system messages included in each request.

```ruby
chat = RubyLLM.chat

chat.with_instructions "Explain Ruby concepts to a beginner. Use short, runnable examples."

response = chat.ask "What is a variable?"
puts response.content
# => "Imagine you have a special box, and you can put things in it..."

# By default, with_instructions replaces the active system instruction
chat.with_instructions "Always end your response with 'Got it?'"

response = chat.ask "What is a loop?"
puts response.content
# => "A loop is like singing your favorite song over and over again... Got it?"

# Append an additional system instruction only when needed
chat.with_instructions "Use exactly one short paragraph.", append: true

# Clear system instructions
chat.with_instructions(nil)
```

--------------------------------

### Getting Structured Output with Schematist

Source: https://rubyllm.com/getting-started

Define a schema class and pass it to with_schema to get structured output 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"
puts response.content
```

--------------------------------

### Using a resource from an MCP server

Source: https://rubyllm.com/api/RubyLLM/MCP/Resource.html

Shows how to fetch a resource by URI, access its content, save it to a file, and pass it to a chat. Resources are read from the server the first time their content is needed.

```ruby
readme = files.resource("file:///project/README.md")
readme.content                 # => "# My Project..."
readme.save("README.md")
chat.ask "Summarize this", with: readme
```

--------------------------------

### Define an agent with model, instructions, and tools

Source: https://rubyllm.com/getting-started

Defines an agent with a model, instructions, and tools (using the CurrentTime tool from the previous example). The agent can be instantiated and asked questions.

```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
```

--------------------------------

### Start a conversation with RubyLLM.chat

Source: https://rubyllm.com/chat

Starts a conversation with the configured default model and sends a question. The response is stored in the `response` variable.

```ruby
chat = RubyLLM.chat
response = chat.ask "Explain the concept of 'Convention over Configuration'."
```

--------------------------------

### api_base override example

Source: https://rubyllm.com/api/RubyLLM/Provider.html

Example override that returns the configured base URL or a default. Relative endpoint paths resolve against this URL.

```ruby
def api_base
  @config.acme_api_base || 'https://api.acme.ai/v1'
end
```

--------------------------------

### after_change usage examples

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Shows how to register a callback for server changes using a method name or a block. The callback receives :tools, :prompts, :resources, an MCP::Resource, or an MCP::Task.

```ruby
after_change :refresh
after_change { |change| Rails.cache.delete("handbook/tools") if change == :tools }

```

--------------------------------

### Price provider tool usage with PRICE_PER_SEARCH

Source: https://rubyllm.com/cost-and-usage-tracking

Price provider tool usage at your provider's published rate. This example calculates the cost of web searches by multiplying the count from server_tool_use by a per-search price. Unless the provider reports the price of a request, cost.total prices tokens only, so add the search cost to it. OpenRouter, Perplexity, and xAI report the price with their tool charges included, and cost.total already uses it.

```ruby
PRICE_PER_SEARCH = 0.01 # US dollars, from your provider's price list

searches = response.tokens.server_tool_use.to_h.fetch("web_search_requests", 0)
search_cost = searches * PRICE_PER_SEARCH

```

--------------------------------

### caching usage examples

Source: https://rubyllm.com/api/RubyLLM/Agent.html

Usage examples for the caching class method: enable with defaults, disable, pass options, or defer evaluation with a block.

```ruby
caching
caching false
caching ttl: "1h"
caching { { ttl: workspace.cache_ttl } }

```

--------------------------------

### Attach a video file with `with:`

Source: https://rubyllm.com/attachments

Send a local video file to a video-capable model using the `with:` parameter. Choose a model that accepts video input, such as `gemini-3.7-flash`.

```ruby
chat = RubyLLM.chat(model: "gemini-3.7-flash")
response = chat.ask "What happens in this video?", with: "demo.mp4"
puts response.content
```

--------------------------------

### Override setup and teardown in Ruby evaluation

Source: https://rubyllm.com/evaluation-running

Override setup and teardown to prepare and clean up application state for each evaluation case. Each case runs on a fresh instance, so instance variables never leak between cases. teardown runs after every case, even when setup, perform, or an assertion fails.

```ruby
def setup
  @order = Order.create!(status: "shipped")
end

def teardown
  @order&.destroy
end

```

--------------------------------

### Skip ActiveStorage with install generator

Source: https://rubyllm.com/rails-generators

Use --skip-active-storage only when you won't send files to models. Default installs ActiveStorage for file attachments.

```bash
# Skip ActiveStorage if you don't need file attachments
bin/rails generate ruby_llm:install --skip-active-storage
```

--------------------------------

### Generate a Support Agent with ruby_llm:agent

Source: https://rubyllm.com/rails-generators

Creates a starter agent class and prompt template. Run from the Rails app root. Generates app/agents/support_agent.rb and app/prompts/support_agent/instructions.txt.erb.

```bash
bin/rails generate ruby_llm:agent Support
```

--------------------------------

### Fluent configuration with with_temperature and with_max_output_tokens

Source: https://rubyllm.com/chat-request-control

Chainable with_* methods configure chat parameters. This example sets temperature to 0.2 and max output tokens to 200.

```ruby
chat = RubyLLM.chat
              .with_temperature(0.2)
              .with_max_output_tokens(200)
```

--------------------------------

### retry_delay override example

Source: https://rubyllm.com/api/RubyLLM/Provider.html

Example override that reads the x-acme-ratelimit-reset header and converts it to a float, returning the number of seconds to wait before retrying a rate-limited request.

```ruby
def retry_delay(response)
  response.response_headers['x-acme-ratelimit-reset']&.to_f
end
```

--------------------------------

### Render partials with render from instructions.txt.erb

Source: https://rubyllm.com/prompt-rendering

Shows how to insert partials using `render` from `app/prompts/work_assistant/instructions.txt.erb`. The first render looks for a partial next to the current prompt, and the second looks in the prompt roots.

```erb
<%= render "tone", display_name: display_name %>
<%= render "shared/safety" %>

```

--------------------------------

### before_input_request usage examples

Source: https://rubyllm.com/api/RubyLLM/MCP.html

Shows how to register a callback for input requests using a method name or a block. The callback receives an MCP::InputRequest to answer or decline.

```ruby
before_input_request :ask_operator
before_input_request { |request| request.answer(environment: "staging") }

```

--------------------------------

### account_identity override example

Source: https://rubyllm.com/api/RubyLLM/Provider.html

Example override that builds an identity from the endpoint and API key. Digest anything secret and leave out credentials that rotate, such as session tokens.

```ruby
def account_identity
  Digest::SHA256.hexdigest([api_base, @config.acme_api_key].join("\0"))
end
```

--------------------------------

### Get structured output with a schema

Source: https://rubyllm.com/getting-started

Defines a schema with Schematist (included with RubyLLM) and gets structured output as a Hash. The parsed result matches the schema fields.

```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}
```

--------------------------------

### Use resource templates

Source: https://rubyllm.com/mcp

Lists resource templates and fills one in with keywords to read a specific resource.

```ruby
files.resource_templates # => [#<RubyLLM::MCP::ResourceTemplate uri: "file:///{+path}", name: "Project files">]
files.resource("file:///{+path}", path: "app/models/user.rb")
```

--------------------------------

### Create a runtime MCP server with dynamic name and prefix

Source: https://rubyllm.com/mcp

Create an inline MCP server at runtime with a dynamic name and prefix. A server with a `transport:` also needs a `name:`, since it has no URL or command to be named after.

```ruby
RubyLLM.mcp(url: server.endpoint, name: "mcp_#{server.id}", prefix: "mcp_#{server.id}", oauth: { owner: server })
```

--------------------------------

### RubyLLM.moderate usage examples

Source: https://rubyllm.com/api/RubyLLM/Moderation.html

Examples of calling RubyLLM.moderate with a single string, an array of strings, and a string with an image attachment. The array form returns a Moderation with multiple results.

```ruby
RubyLLM.moderate("User message")
RubyLLM.moderate(["First comment", "Second comment"]).results
RubyLLM.moderate("Caption", with: "screenshot.png")

```

--------------------------------

### Suggest completions with RubyLLM MCP

Source: https://rubyllm.com/mcp

Shows how to use the suggest method on prompts and resource templates to get completion suggestions. The first keyword is the value to complete; the rest provide context.

```ruby
review = github.prompts.first
review.suggest(language: "ru")
# => ["ruby", "rust"]
files.resource_templates.first.suggest(path: "app/mo")
```

--------------------------------

### Start a background research task with research_later

Source: https://rubyllm.com/hosted-research

Starts a background research task and returns a job object immediately without waiting. Save the job ID for later retrieval.

```ruby
job = RubyLLM.research_later(
  "Find the official Ruby documentation and explain where its API reference lives.",
  provider: :vertexai,
  agent: "deep-research-preview-04-2026"
)
job.id
job.status # => :pending
```
Tokens:
Raw