agentleFS
kaka-rutokaka-ruto/skills/rubyllm/SKILL.md

rubyllm

Skill4 starsChanged 7 months agoMITView on GitHub

One beautiful Ruby API for GPT, Claude, Gemini, and more. Use this skill when building AI-powered applications with RubyLLM - chatbots, AI agents, RAG applications, content generators, vision/audio analysis, embeddings, image generation, and Rails integration. Supports 15+ providers with a unified interface.

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. crmne/ruby_llm★ 4.5ksame name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

Files
SKILL.md

RubyLLM v{{ page.version }}

One beautiful Ruby API for GPT, Claude, Gemini, and more.

RubyLLM provides a unified interface for working with AI models across 15+ providers. Build chatbots, AI agents, RAG applications, and content generators with the same simple API.

Gem Version: 1.14.1

Installation

Ruby Project

bundle add ruby_llm
# config/initializers/ruby_llm.rb
RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
  config.gemini_api_key = ENV['GEMINI_API_KEY']
end

Rails Integration

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

# Optional: Add chat UI
bin/rails generate ruby_llm:chat_ui
# Visit http://localhost:3000/chats

Quick Start

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

# Stream responses
chat.ask "Write a story" do |chunk|
  print chunk.content
end

# With tools
class Weather < RubyLLM::Tool
  description "Get weather"
  param :city, desc: "City name"
  def execute(city:)
    "Sunny in #{city}"
  end
end

chat.with_tool(Weather).ask "Weather in Paris?"

Core Features

FeatureSkill Reference
ChatThis skill (below)
Toolstools
Agentsagents
StreamingThis skill (Streaming section)
Embeddingsembeddings
Image Generationimage-generation
Audio Transcriptionaudio-transcription
Moderationmoderation
Extended ThinkingThis skill (Extended Thinking section)
Rails Integrationrails

Ecosystem Gems

GemVersionSkill Reference
ruby_llm-schema0.3.0schema
ruby_llm-mcp1.0.0mcp
ruby_llm-instrumentation0.3.1instrumentation
ruby_llm-monitoring0.3.2monitoring
ruby_llm-red_candle0.2.0red_candle
ruby_llm-tribunal0.1.1tribunal
opentelemetry-instrumentation-ruby_llm0.4.0opentelemetry

Chat API

# Create chat
chat = RubyLLM.chat(model: 'gpt-5.4')

# Ask question
response = chat.ask "What is Ruby?"

# Continue conversation (remembers context)
chat.ask "Show me an example"

# Access messages
chat.messages.each do |msg|
  puts "[#{msg.role}] #{msg.content}"
end

# System instructions
chat.with_instructions "You are a Ruby expert. Be concise."

Providers

RubyLLM supports 15+ providers through a unified API:

ProviderModelsVisionToolsAudio
OpenAIGPT-4, GPT-4o, o1, o3✅✅✅
AnthropicClaude 3/4✅✅❌
GoogleGemini 1.5/2.0/2.5/3.0✅✅✅
xAIGrok-1/2/3✅✅❌
AWS BedrockClaude, Llama, Titan✅✅❌
OllamaLocal models✅✅✅
OpenRouter300+ models✅✅❌
PerplexitySearch models❌✅❌
MistralMistral/Mixtral✅✅❌
DeepSeekDeepSeek-V3❌✅❌
VertexAIGoogle Cloud✅✅✅
GPUStackSelf-hosted✅✅❌
Azure OpenAIEnterprise OpenAI✅✅✅

Provider Setup

RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
  config.gemini_api_key = ENV['GEMINI_API_KEY']
  config.xai_api_key = ENV['XAI_API_KEY']
  config.perplexity_api_key = ENV['PERPLEXITY_API_KEY']
  config.mistral_api_key = ENV['MISTRAL_API_KEY']
  config.deepseek_api_key = ENV['DEEPSEEK_API_KEY']
end

Model Selection

# By model ID
chat = RubyLLM.chat(model: 'claude-sonnet-4-6')

# By provider routing
chat = RubyLLM.chat(model: 'claude-sonnet-4-6', provider: 'bedrock')

# Model registry
RubyLLM.models.supporting(:vision)
RubyLLM.models.find('gpt-5.4')

Prompt Caching (Anthropic)

raw_block = RubyLLM::Content::Raw.new([
  { 
    type: 'text', 
    text: File.read('large_document.txt'),
    cache_control: { type: 'ephemeral' }
  }
])

chat.add_message(role: :system, content: raw_block)
response = chat.ask(raw_block)
puts "Cached tokens: #{response.cached_tokens}"

Extended Thinking

Give models more computation budget for complex reasoning (o1, o3, Claude Opus).

New in v1.10

# Enable with effort level
chat = RubyLLM.chat(model: 'claude-opus-4.5')
  .with_thinking(effort: :high)

response = chat.ask("Complex problem")

# Access thinking trace
puts response.thinking&.text
puts response.thinking&.signature
puts response.thinking_tokens

Effort Levels

chat.with_thinking(effort: :low)     # Fast, cheap
chat.with_thinking(effort: :medium)  # Balanced
chat.with_thinking(effort: :high)    # Slow, accurate
chat.with_thinking(effort: :none)    # Disable
chat.with_thinking(budget: 10_000)   # Token cap

Streaming with Thinking

chat.ask "Solve step by step" do |chunk|
  print chunk.thinking&.text  # Some providers stream thinking
  print chunk.content
end

Streaming

chat.ask "Write a story" do |chunk|
  print chunk.content
  $stdout.flush
end

# With events
chat = RubyLLM.chat
  .on_new_message { print "Assistant > " }
  .on_end_message { |msg| puts "\n✓ Done (#{msg.output_tokens} tokens)" }

chat.ask "Hello" do |chunk|
  print chunk.content
end

Multi-Modal

# Images
chat.ask "What's in this image?", with: "photo.jpg"

# PDFs
chat.ask "Summarize this", with: "report.pdf"

# Audio
chat.ask "Transcribe", with: "meeting.mp3"

# Multiple files
chat.ask "Analyze", with: ["image.jpg", "doc.pdf", "notes.txt"]

Token Tracking

response = chat.ask "Hello"

puts "Input: #{response.input_tokens}"
puts "Output: #{response.output_tokens}"
puts "Cached: #{response.cached_tokens}"
puts "Thinking: #{response.thinking_tokens}"

# Cost estimation
model = RubyLLM.models.find(response.model_id)
cost = (response.input_tokens * model.input_price_per_million / 1_000_000) +
       (response.output_tokens * model.output_price_per_million / 1_000_000)

Error Handling

begin
  response = chat.ask "Hello"
rescue RubyLLM::AuthenticationError
  # Invalid API key
rescue RubyLLM::RateLimitError => e
  sleep e.retry_after
  retry
rescue RubyLLM::TimeoutError
  # Request timeout
rescue RubyLLM::ContextLengthExceededError
  # Reduce prompt size
rescue RubyLLM::Error => e
  # Generic API error
end

Error Types

ErrorHTTPDescription
BadRequestError400Invalid parameters
UnauthorizedError401Invalid API key
PaymentRequiredError402Billing issue
RateLimitError429Rate limit exceeded
ContextLengthExceededError-Token limit
ServerError500Provider error
ServiceUnavailableError502/503/504Service down

Debugging

export RUBYLLM_DEBUG=true

Shows full request/response details in logs.

Best Practices

Tool Security

class SafeTool < RubyLLM::Tool
  param :input, desc: "User input"

  def execute(input:)
    raise ArgumentError if input.length > 1000
    # NEVER use: eval, system, exec, `
  end
end

Cost Control

simple_chat = RubyLLM.chat(model: 'gpt-5-nano')  # Cheap
complex_chat = RubyLLM.chat(model: 'claude-sonnet-4-6')  # Capable

Context Management

if chat.messages.sum { |m| m.input_tokens + m.output_tokens } > 100_000
  summary = summarize(chat.messages.first(40))
  chat.reset_messages!
  chat.add_message(role: :system, content: summary)
end

Resources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.