Skip to content
Back to search

ruby_llm

The Ruby-native AI framework. Chats, agents, tools, images, audio, and video through one consistent API, in plain Ruby or Rails.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/crmne/ruby_llm with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/crmne/ruby_llm'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/crmne--ruby-llm/badge.svg)](/listings/crmne--ruby-llm)

HTML

<a href="/listings/crmne--ruby-llm"><img src="/api/listings/crmne--ruby-llm/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install RubyLLM 2.1:

bundle add ruby_llm --version 2.1.1

Configure a provider in 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

Configure the other providers used by the examples as needed: Gemini for files, xAI for video, Mistral for OCR, and Cohere for reranking. [Getting Started](https://rubyllm.com/getting-started/) shows each setup beside its example. Upgrading an existing app? Follow the [upgrade guide](https://rubyllm.com/upgrading/).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 26 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "ruby_llm",
  3. "description": "The RubyLLM skill for building Ruby and Rails applications with the RubyLLM AI framework.",
  4. "owner": {
  5. "name": "Carmine Paolino",
  6. "url": "https://rubyllm.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "rubyllm",
  11. "displayName": "RubyLLM",
  12. "source": "./skills",
  13. "skills": ["./rubyllm"],
  14. "description": "Build and maintain Ruby or Rails applications with RubyLLM: chats, agents, tools, MCP, structured output, evaluations, media, embeddings, and Rails integration.",
  15. "author": {
  16. "name": "Carmine Paolino",
  17. "url": "https://paolino.me"
  18. },
  19. "homepage": "https://rubyllm.com/ai-coding-assistants/",
  20. "repository": "https://github.com/crmne/ruby_llm",
  21. "license": "MIT",
  22. "keywords": ["ruby", "rails", "ai", "llm", "agents"],
  23. "category": "development"
  24. }
  25. ]
  26. }
README.md · README · 356 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="/docs/assets/images/logotype_dark.svg">
  4. <img src="/docs/assets/images/logotype.svg" alt="RubyLLM" height="120" width="250">
  5. </picture>
  6. <strong>The Ruby AI framework</strong>
  7. <p>Build AI features the Ruby way: models, tools, agents, evaluations, and Rails conventions, designed together, with one consistent API.</p>
  8. </div>
  9. ```ruby
  10. chat = RubyLLM.chat
  11. chat.ask "What's the best way to learn Ruby?"
  12. chat.ask "What's in this image?", with: "ruby_conf.jpg"
  13. chat.with_model("claude-sonnet-5").ask "Now say it as a haiku"
  14. RubyLLM.paint("a sunset over mountains in watercolor").save("sunset.png")
  15. ```
  16. <div align="center">
  17. [Website](https://rubyllm.com/) · [Getting Started](https://rubyllm.com/getting-started/) · [What's New in 2.2](https://rubyllm.com/whats-new-in-2-2/)
  18. Battle tested at [<picture><source media="(prefers-color-scheme: dark)" srcset="https://chatwithwork.com/logotype-dark.svg"><img src="https://chatwithwork.com/logotype.svg" alt="Chat with Work" height="30" align="absmiddle"></picture>](https://chatwithwork.com) - *Fully private work AI*
  19. [![Gem Version](https://badge.fury.io/rb/ruby_llm.svg)](https://badge.fury.io/rb/ruby_llm)
  20. [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
  21. [![Gem Downloads](https://img.shields.io/gem/dt/ruby_llm)](https://rubygems.org/gems/ruby_llm)
  22. [![codecov](https://codecov.io/gh/crmne/ruby_llm/branch/main/graph/badge.svg)](https://codecov.io/gh/crmne/ruby_llm)
  23. <a href="https://trendshift.io/repositories/13640" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13640" alt="crmne%2Fruby_llm | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
  24. </div>
  25. https://github.com/user-attachments/assets/519fcb20-ab8c-4af3-9185-0953b3ba7b81
  26. > [!NOTE]
  27. > Using RubyLLM? [Share your story](https://tally.so/r/3Na02p)! Takes 5 minutes.
  28. ---
  29. ## 23 providers. One API.
  30. Build with the models you want. Move between hosted and local providers without rewriting your application, or connect an OpenAI-compatible endpoint.
  31. [Browse models and pricing](https://rubyllm.com/available-models/) · [Connect a provider](https://rubyllm.com/configuration-providers/)
  32. ## A complete AI framework for Ruby
  33. More than a client for model APIs. RubyLLM gives your application the conventions, the runtime, and every piece in between, designed to work together. Everything below ships in RubyLLM 2.2.
  34. ### Conversations
  35. * **Chat:** Conversational AI with `RubyLLM.chat`
  36. * **Streaming:** Real-time responses with blocks
  37. * **Attachments:** Ask about images, videos, audio, PDFs, and other documents with `with:`
  38. * **Structured output:** Define a Ruby schema and read the result with `response.parsed`
  39. * **Extended thinking:** Control, view, and persist model deliberation
  40. * **Citations:** Normalized source citations from documents, search, and grounding
  41. * **Prompt caching:** Turn on the provider's cache with `with_caching` and `cache_until_here`
  42. * **Compaction:** Let providers condense long conversations with `with_compaction`
  43. * **Token counting:** Count a request before you send it with `count_tokens`
  44. * **Fallbacks and cancellation:** Retry on backup models with `with_fallbacks`, stop a run with `cancel`
  45. ### Tools and agents
  46. * **Tools:** Let AI call your Ruby methods
  47. * **Tool approval:** Park a run until a human approves with `requires_approval`
  48. * **Provider tools:** Web search, code execution, and MCP connectors with `with_provider_tools`
  49. * **MCP:** Connect agents to your systems with server classes in `app/mcp`, per-user inputs, tool filtering, and OAuth with [`RubyLLM::MCP`](https://rubyllm.com/mcp/)
  50. * **Agents:** Reusable assistants with `RubyLLM::Agent`
  51. * **The agentic loop:** Drive it yourself with `ask_later`, `step`, and `complete?`
  52. * **Prompt templates:** ERB prompts in `app/prompts`, rendered with `RubyLLM.render_prompt`
  53. * **Workflows:** Correlate multi-agent runs in your telemetry with `RubyLLM.workflow`
  54. * **Evaluations:** Reusable datasets, model criteria, and Ruby assertions with [`RubyLLM::Evaluation`](https://rubyllm.com/evaluations/)
  55. * **Judgments:** Probabilities, choices, and scores with `RubyLLM::Judge` and `RubyLLM.judge`
  56. ### Individual operations
  57. * **Image generation:** Create images with `RubyLLM.paint`
  58. * **Video generation:** Create videos with `RubyLLM.animate`
  59. * **Audio:** Transcribe speech with `RubyLLM.transcribe` and generate it with `RubyLLM.speak`
  60. * **OCR:** Turn documents into markdown with `RubyLLM.ocr`
  61. * **Embeddings:** Generate embeddings with `RubyLLM.embed`
  62. * **Reranking:** Order retrieval candidates by relevance with `RubyLLM.rerank`
  63. * **Moderation:** Content flags, categories, and scores with `RubyLLM.moderate`
  64. * **Files:** Upload once and reuse across chats with `RubyLLM.upload`
  65. * **Batches:** Provider-side batch processing with provider-specific discounts via `RubyLLM.batch`
  66. ### Rails and production
  67. * **Rails:** Active Record persistence, Active Storage attachments, Hotwire streaming, and generators
  68. * **Cost tracking:** A per-attempt usage ledger behind `chat.tokens` and `chat.cost`
  69. * **Observability:** Instrumentation events and OpenTelemetry tracing
  70. * **Async:** Fiber-based concurrency
  71. * **Model registry:** Browse capabilities, limits, and pricing across providers
  72. * **Providers:** OpenAI, Azure, xAI, Anthropic, Gemini, VertexAI, Bedrock, Cohere, DeepSeek, Hetzner, Meta, MiniMax, Mistral, Moonshot AI, Ollama, Ollama Cloud, OpenRouter, Perplexity, GPUStack, ElevenLabs, Deepgram, TypeSafe, Z.ai, and any OpenAI-compatible API
  73. ### New in 2.2
  74. * **Code execution:** Let the model run Ruby, Python, JavaScript, and shell in a sandbox on your servers with [`with_code_execution`](https://rubyllm.com/code-execution/)
  75. * **Skills:** Teach the model your workflows with folders of instructions and scripts in the Agent Skills format with [`with_skills`](https://rubyllm.com/skills/)
  76. * **File stores:** Keep attachments and long tool results out of the conversation with [`with_file_store`](https://rubyllm.com/file-stores/)
  77. * **Message queueing:** Add messages while a chat runs with `queue`
  78. * **More providers:** Meta, MiniMax, Moonshot AI, and Z.ai
  79. ## Evaluate your agents
  80. Keep questions and expected answers in a dataset. RubyLLM checks correctness by default. Run the same evaluation from Ruby, RSpec, Minitest, or Rake.
  81. `app/agents/support_agent.rb`
  82. ```ruby
  83. class SupportAgent < RubyLLM::Agent
  84. instructions "Accept returns of unopened items within 30 days."
  85. end
  86. ```
  87. `app/evals/support_evaluation.rb`
  88. ```ruby
  89. class SupportEvaluation < RubyLLM::Evaluation
  90. def perform(input)
  91. SupportAgent.new.ask(input)
  92. end
  93. end
  94. ```
  95. `app/evals/support_evaluation.yml`
  96. ```yaml
  97. cases:
  98. - name: within_return_window
  99. inputs: Can I return an unopened item after 14 days?
  100. expected_output: Yes, unopened items can be returned within 30 days.
  101. - name: past_return_window
  102. inputs: Can I return an unopened item after 45 days?
  103. expected_output: No, the 30-day return window has passed.
  104. ```
  105. Run the evaluation:
  106. ```ruby
  107. report = SupportEvaluation.run
  108. report.passed?
  109. report.cost.total
  110. ```
  111. The model evaluator checks meaning, so answers can use different wording. Declare your own criteria, add Ruby assertions, or choose a configured evaluator agent or judgment model. [Read the evaluation guides](https://rubyllm.com/evaluations/).
  112. ## Feels at home in Rails
  113. Save conversations with Active Record and stream replies with Hotwire. The generators give you a working chat UI. Watch the two-minute demo.
  114. https://github.com/user-attachments/assets/65422091-9338-47da-a303-92b918bd1345
  115. ```bash
  116. # Install Rails Integration
  117. bin/rails generate ruby_llm:install
  118. bin/rails db:migrate
  119. bin/rails ruby_llm:load_models
  120. # Add Chat UI (optional)
  121. bin/rails generate ruby_llm:chat_ui
  122. ```
  123. ```ruby
  124. class Chat < ApplicationRecord
  125. acts_as_chat
  126. end
  127. chat = Chat.create! model: "gpt-6-luna"
  128. chat.ask "What's in this file?", with: "report.pdf"
  129. ```
  130. Start your Rails server and visit `http://localhost:3000/chats` to try the chat interface. See the [Rails guide](https://rubyllm.com/rails/) for persistence, streaming, and background jobs.
  131. ## Start with one line. Add files, tools, and agents
  132. These examples use **2.2.2**. Follow [Getting Started](https://rubyllm.com/getting-started/) to install it and configure the providers you want to try. For 1.x, use the [1.x docs](https://rubyllm.com/v1/).
  133. ```ruby
  134. # Just ask
  135. RubyLLM.chat.ask "What's the best way to learn Ruby?"
  136. ```
  137. ```ruby
  138. # Ask about files with a model that supports their input types
  139. chat = RubyLLM.chat(model: "gemini-3.7-flash")
  140. chat.ask "What's in this image?", with: "ruby_conf.jpg"
  141. chat.ask "What's happening in this video?", with: "video.mp4"
  142. chat.ask "Describe this meeting", with: "meeting.wav"
  143. chat.ask "Summarize this document", with: "contract.pdf"
  144. chat.ask "Explain this code", with: "app.rb"
  145. ```
  146. ```ruby
  147. # Multiple files at once
  148. chat.ask "Analyze these files", with: ["diagram.png", "report.pdf", "notes.txt"]
  149. ```
  150. ```ruby
  151. # Stream responses
  152. chat.ask "Tell me a story about Ruby" do |chunk|
  153. print chunk.content
  154. end
  155. ```
  156. ```ruby
  157. # Generate images
  158. image = RubyLLM.paint "a sunset over mountains in watercolor style"
  159. image.save "sunset.png"
  160. ```
  161. ```ruby
  162. # Generate videos
  163. video = RubyLLM.animate "a paper boat sailing down a rainy gutter"
  164. video.save "paper_boat.mp4"
  165. ```
  166. ```ruby
  167. # Create embeddings
  168. embedding = RubyLLM.embed "Ruby is elegant and expressive"
  169. embedding.vector
  170. ```
  171. ```ruby
  172. # Rank search results
  173. documents = ["Reset your password in Settings.", "Invoices arrive by email."]
  174. ranked = RubyLLM.rerank("How do I reset my password?", documents, model: "rerank-v3.5")
  175. ranked.results.first.document
  176. ```
  177. ```ruby
  178. # Transcribe audio to text
  179. transcript = RubyLLM.transcribe "meeting.wav"
  180. puts transcript.text
  181. ```
  182. ```ruby
  183. # Turn text into speech
  184. speech = RubyLLM.speak "Hello, welcome to RubyLLM!"
  185. speech.save "welcome.mp3"
  186. ```
  187. ```ruby
  188. # Extract document text as markdown
  189. document = RubyLLM.ocr "contract.pdf"
  190. puts document.markdown
  191. ```
  192. ```ruby
  193. # Check whether a moderation model flags content
  194. RubyLLM.moderate("Some user-generated content").flagged?
  195. ```
  196. ```ruby
  197. # Ask a typed question about your data
  198. class Urgency < RubyLLM::Judge
  199. probability :urgent, "Does this need attention today?"
  200. end
  201. Urgency.judge("Please refund my duplicate charge today.").urgent.probability
  202. ```
  203. ```ruby
  204. # Let AI use your code
  205. class Weather < RubyLLM::Tool
  206. description "Get current weather"
  207. def execute(latitude:, longitude:)
  208. url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
  209. JSON.parse(Faraday.get(url).body)
  210. end
  211. end
  212. chat.with_tools(Weather).ask "What's the weather in Berlin?"
  213. ```
  214. ```ruby
  215. # Define an agent with instructions + tools
  216. class WeatherAssistant < RubyLLM::Agent
  217. model "gpt-6-luna"
  218. instructions "Be concise and always use tools for weather."
  219. tools Weather
  220. end
  221. WeatherAssistant.new.ask "What's the weather in Berlin?"
  222. ```
  223. ```ruby
  224. # Get structured output
  225. class ProductSchema < Schematist::Schema
  226. string :name
  227. number :price
  228. array :features do
  229. string
  230. end
  231. end
  232. response = chat.with_schema(ProductSchema).ask "Analyze this product", with: "product.txt"
  233. response.parsed
  234. ```
  235. ## Installation
  236. Install RubyLLM 2.2:
  237. ```bash
  238. bundle add ruby_llm --version 2.2.2
  239. ```
  240. Configure a provider in your script, or in `config/initializers/ruby_llm.rb` in Rails:
  241. ```ruby
  242. require 'ruby_llm'
  243. RubyLLM.configure do |config|
  244. config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
  245. end
  246. ```
  247. Configure the other providers used by the examples as needed: Gemini for files, xAI for video, Mistral for OCR, and Cohere for reranking. [Getting Started](https://rubyllm.com/getting-started/) shows each setup beside its example. Upgrading an existing app? Follow the [upgrade guide](https://rubyllm.com/upgrading/).
  248. Coming from ruby-openai or langchainrb? Follow the [ruby-openai migration guide](https://rubyllm.com/migrate/ruby-openai/), or see [every migration and comparison guide](https://rubyllm.com/migrating-from/).
  249. ## AI coding assistants
  250. Give your coding assistant the RubyLLM API and documentation that match your application. From your application directory, install the skill packaged with your gem:
  251. ```bash
  252. gem exec skill add "$(bundle show ruby_llm)" --skill rubyllm --agents coding
  253. ```
  254. `--agents coding` installs it for the coding assistants your project uses, not into your app's `app/skills`. In Claude Code, you can also install it as a plugin:
  255. ```
  256. /plugin marketplace add crmne/ruby_llm
  257. /plugin install rubyllm@ruby_llm
  258. ```
  259. See [AI Coding Assistants](https://rubyllm.com/ai-coding-assistants/) for setup and updates.
  260. ## Documentation
  261. [Guides](https://rubyllm.com/getting-started/) · [API reference](https://rubyllm.com/api/) · [Models](https://rubyllm.com/available-models/) · [Upgrading](https://rubyllm.com/upgrading/) · [1.x docs](https://rubyllm.com/v1/)
  262. ## Contributing
  263. See [CONTRIBUTING.md](CONTRIBUTING.md).
  264. ## License
  265. Released under the MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.