crmne/ruby_llm

RubyLLM is a Ruby library and Rails integration framework that provides a unified interface for interacting with a wide variety of AI model providers, supporting capabilities such as chat, image generation, speech synthesis, and embeddings. It includes a comprehensive set of Rails generators to scaffold agents, chat interfaces with real-time streaming, custom tools, and schema definitions, while managing database persistence for chats, messages, and usage tracking. The system also features a built-in Model Context Protocol (MCP) client, scoped configuration contexts for multi-tenancy, and extensive tooling for provider development and conformance testing.

23 changes.

This period focused on the major 2.0 release of the RubyLLM library, featuring a comprehensive framework rewrite, expanded provider support, and new capabilities like MCP client integration. Significant effort was dedicated to deepening Rails integration through new generators for installation and chat UI scaffolding, alongside robust ActiveRecord-backed models for chat, usage tracking, and media attachments. The work was supported by a complete overhaul of the test infrastructure, dependency management, and developer tooling to ensure stability and ease of use.

18 changes.

This period focused on expanding the RubyLLM Rails generators to scaffold agents, schemas, tools, and standalone provider gems, while introducing a CLI entry point. The chat UI was significantly enhanced with comprehensive Tailwind-styled templates for messages, models, and tool interactions, alongside standardized helper logic. Infrastructure improvements included new Rake tasks for model registry management and release hygiene, as well as added conformance testing for the MCP client.

The repository now includes a .env.example file that lists environment variables for all supported providers (such as Anthropic, AWS, Azure, Deepgram, OpenAI, and others) using 1Password CLI syntax as placeholders. This provides a ready-to-use template for developers to configure their local environment with the necessary API keys and endpoints without exposing real credentials.

(repo-wide) · high confidence

A new executable script at exe/ruby\_llm has been added to serve as the command-line interface for the library. This entry point initializes the load path and delegates execution to the RubyLLM::Generators::Provider::CLI, enabling users to run provider-related generator commands directly from the command line.

exe · high confidence

A new \ruby\_llm:load\_models\ task has been added to allow users to load the selected model registry from JSON and persist it into the database. This task ensures the ActiveRecord load hook is triggered correctly, even in environments where ActiveRecord is loaded lazily (such as Rails 8.1), and provides feedback on the number of models successfully saved.

lib/tasks · high confidence

The generator now includes a new set of Tailwind CSS-styled view templates for the chat interface. These templates provide a consistent, responsive design for listing chats, creating new ones, and viewing chat details, including model selection, message history, and navigation controls.

_lib/generators/ruby\_llm/chat\ui/templates/tailwind/views/chats · high confidence

The chat UI generator now includes a template for a background job (ChatResponseJob) that processes chat messages. This job finds the relevant chat record, invokes the model's ask method with the provided content, and broadcasts any non-empty content chunks to the client via the message's broadcast\_append\_chunk method, enabling streaming responses in the generated application.

_lib/generators/ruby\_llm/chat\ui/templates/jobs · high confidence

A new symbolic link named 'contributing' has been added to the .agents/skills directory, pointing to the existing contributing skill definition located in the .claude/skills directory. This change exposes the contributing guidelines as an available skill within the agents configuration.

.agents · high confidence

The generated Rails controllers for the chat UI have been updated to include a destroy action for chats, allowing users to delete conversations. Additionally, a new models controller has been introduced to provide an index of available chat models, a show action for specific model details, and a refresh action to update the list of available models via RubyLLM.

_lib/generators/ruby\_llm/chat\ui/templates/controllers · high confidence

RubyLLM now supports isolated configuration scopes via the new Context class, allowing multi-tenant applications or per-request overrides to use their own API keys and settings without affecting the global configuration. Additionally, a built-in Model Context Protocol (MCP) client is added, enabling direct connection to MCP servers for tool access, prompt templates, and input handling, with credentials securely persisted using the new ActiveRecord models.

_ruby\llm · high confidence

The RubyLLM Rails generator now supports creating custom tool classes along with their corresponding view partials for displaying tool calls and results in the chat UI. The generator produces a base tool class in app/tools that inherits from RubyLLM::Tool, and generates Tailwind or scaffold-styled view partials for rendering tool execution details and outcomes within the message conversation flow.

_lib/generators/ruby\llm/tool · high confidence

Users can now generate RubyLLM schema classes using the new \ruby\_llm:schema\ Rails generator. This tool creates a new file in \app/schemas/\ that inherits from \Schematist::Schema\, automatically handling class naming conventions (appending 'Schema' if missing) and file naming (underscored). This replaces the previous dependency on \ruby\_llm-schema\ with the \schematist\ library, providing a standardized way to define schema structures within Rails applications.

_lib/generators/ruby\llm/schema · high confidence

A new Rails generator (\ruby\_llm:agent\) has been added to scaffold RubyLLM agent classes and their associated instruction prompts. When invoked, it creates an agent class in \app/agents\ that inherits from \RubyLLM::Agent\ (with an optional \chat\_model\ configuration for persistence) and a corresponding prompt directory in \app/prompts\ containing a default \instructions.txt.erb\ file, streamlining the setup of new agent-based features.

_lib/generators/ruby\llm/agent · high confidence

This change introduces several new Rake tasks in the \tasks/\ directory to support model catalog maintenance and release processes. The \models\ task suite (\models:update\, \models:docs\, \models:aliases\) automates fetching model data from providers, validating the registry against a JSON schema using \JSONSchemer\, generating documentation, and handling aliases, with safeguards against suspicious model count drops. A new \conformance\ task runs the official MCP client conformance suite against RubyLLM's MCP implementation. Additionally, \release\ tasks help maintain test hygiene by detecting and refreshing stale VCR cassettes before release, and \vcr\ tasks allow recording or retimestamping cassettes for specific providers.

tasks · high confidence

The RubyLLM gem now provides a dedicated \ruby\_llm:install\ generator to streamline Rails integration. Running this generator creates the necessary database migrations for chat and message records, generates the corresponding model files, sets up an initializer for API configuration, and establishes convention directories for agents, tools, schemas, and prompts. It also handles ActiveStorage setup for file attachments (unless skipped) and provides clear next-step instructions for running migrations and starting to use the library.

_lib/generators/ruby\llm/install · high confidence

The Ruby LLM generator now includes a complete set of Tailwind-styled view templates for rendering chat messages. When generating a chat UI, users will receive distinct partials for different message types: user and assistant messages with styled headers and timestamps, system messages with a neutral gray theme, error messages with red styling, and a new convention for tool calls that delegates to specific tool result partials. These templates provide the visual structure for the generated chat interface, replacing any previous or default styling with a consistent, responsive Tailwind design.

_lib/generators/ruby\_llm/chat\ui/templates/tailwind/views/messages · high confidence

The generated Rails chat UI now includes Tailwind-styled templates for browsing and viewing AI models. Users will see a model index page listing provider, name, context window, and per-million-token pricing, along with a show page displaying model details and capabilities. Both views include navigation links to start new chat sessions with the selected model.

_lib/generators/ruby\_llm/chat\ui/templates/tailwind/views/models · high confidence

Adds a new \ruby\_llm:chat\_ui\ generator that scaffolds a complete chat interface, including controllers, views, jobs, and helpers. The generator supports multiple UI styles (scaffold, Tailwind, or auto-detection) and implements real-time updates via Turbo streaming with \broadcasts\_to\. It also handles namespaced models correctly, injects broadcasting logic into message models, and adds routes for managing chats, messages, and AI models.

_lib/generators/ruby\_llm/chat\ui · high confidence

Added five new executable scripts to streamline the developer experience: \bin/console\ provides an interactive Ruby environment with pre-configured API keys for all supported providers (Anthropic, Azure, Bedrock, DeepSeek, Gemini, GPUStack, Mistral, Ollama, OpenAI, OpenRouter, Perplexity, Vertex AI, and xAI) via environment variables; \bin/setup\ automates dependency installation; \bin/test\ runs the test suite using a custom \rspec-queue\ runner that isolates databases per worker and merges SimpleCov coverage, with a fallback to standard RSpec for JRuby; \bin/rspec-queue\ implements this custom runner logic; and \bin/gitleaks-staged\ adds a pre-commit hook to scan staged files for secrets.

bin · high confidence

The chat UI generator now includes dedicated views for managing AI models. Users will see a new Models index page listing available models with their provider, name, context window, and input/output pricing, along with a refresh action. A partial renders each model row, and a show view displays detailed model information including ID, capabilities, and max output tokens, with links to start a new chat or return to the list.

_lib/generators/ruby\_llm/chat\ui/templates/views/models · high confidence

The RubyLLM tooling now includes a generator that creates a complete, standalone provider gem. Running the generator produces a full project structure including the provider implementation, a Gemfile with development dependencies (RSpec, RuboCop, VCR, WebMock), and a comprehensive suite of live integration specs covering chat, streaming, tools, embeddings, image generation, speech, video, and moderation. It also scaffolds CI workflows for testing across multiple Ruby versions, a release workflow for publishing to RubyGems, and configuration files for linting and security scanning (Gitleaks).

_lib/generators/ruby\llm/provider · high confidence

A new executable script at script/generate-provider has been added to the project. This tool allows users to generate new provider implementations by invoking the RubyLLM generator scaffolding, providing a streamlined way to create core provider changes and handle existing files.

script · high confidence

The \acts\_as\_chat\ and \acts\_as\_message\ helpers in the Rails integration now fully support Action Text rich content and Active Storage attachments. Messages can include Action Text content with embedded attachments, which are automatically extracted and persisted to Active Storage. The integration handles both incoming attachments from the LLM and outgoing attachments from the user, including file uploads and URL-based attachments. This enables richer conversations with media support in Rails applications using the ActiveRecord-backed chat models.

_lib/ruby\llm · high confidence

The chat UI generator templates have been updated to provide a more complete user experience. The index view now includes a link to the model list and a 'Destroy' action for chats. The new chat form allows users to select an AI model from a dropdown and enter a prompt. The show view displays the active model, lists messages, and includes a form for sending new messages, with Turbo streams enabled for real-time updates.

_lib/generators/ruby\_llm/chat\ui/templates/views/chats · high confidence

The library has been significantly refactored, replacing the previous minimal structure with a comprehensive, documented API. The main entry point now includes extensive inline documentation covering new capabilities such as image painting, video animation, speech synthesis, OCR, transcription, embeddings, and typed judgments. The codebase has been expanded to support a wide range of model providers (including Azure, Bedrock, DeepSeek, ElevenLabs, GPUStack, Hetzner, Mistral, OpenRouter, Perplexity, VertexAI, and xAI) and introduces new features like MCP client support, provider-side batching, caching, and workflow instrumentation. The internal architecture has been reorganized using Zeitwerk for autoloading with specific inflections, and the public interface now exposes methods for chat, painting, animating, speaking, transcribing, OCR, embedding, reranking, moderation, research, and judgment.

lib · high confidence

The chat UI generator now includes a new \messages\_helper.rb.tt\ template that standardizes how tool calls and results are rendered. It introduces a \default\_model\_display\_name\ helper to show the configured default model's label, and implements a \partial\_for\ logic that resolves specific partials for tool calls and results (e.g., \tool\_calls/\<tool\_name\>\ or \tool\_results/\<tool\_name\>\) with a fallback to a \default\ partial if a specific one is not found. This allows users to customize the appearance of specific tool interactions by providing corresponding view templates.

_lib/generators/ruby\_llm/chat\ui/templates/helpers · high confidence

The chat UI generator templates for message views have been restructured to support distinct message types and improved user experience. New partials have been added to render specific message roles: \\_assistant.html.erb.tt\ and \\_user.html.erb.tt\ for standard chat messages with styling and timestamps, \\_system.html.erb.tt\ for system notifications, and \\_error.html.erb.tt\ for error display. Tool interactions are now handled via \\_tool.html.erb.tt\ and \\_tool\_calls.html.erb.tt\, which delegate to specific tool result and call partials. The \\_form.html.erb.tt\ template has been updated to support namespaced models correctly in form URLs. Additionally, \create.turbo\_stream.erb.tt\ now uses Turbo Streams to replace the form after submission, enabling smoother asynchronous updates without full page reloads.

_lib/generators/ruby\_llm/chat\ui/templates/views/messages · high confidence

The RubyLLM generator helpers have been rewritten to better support namespaced models and offer a Tailwind CSS UI option. The new \GeneratorHelpers\ module introduces logic to automatically create namespace modules when model names include namespaces (e.g., \Admin::Chat\), ensuring correct table name prefixes and association handling. It also adds a \ui\_variant\ method that detects Tailwind availability and switches generated views to Tailwind-specific templates if available, falling back to standard scaffolds otherwise. Additionally, helper methods for model names, table names, and controller class names are now dynamically derived to handle these namespaces correctly, fixing previous issues with namespaced model generation.

_lib/generators/ruby\llm · high confidence

The upgrade generator now provides a migration path from RubyLLM 2.0 to 2.1. This migration introduces a new \ruby\_llm\_mcp\_credentials\ table to store credentials for the built-in MCP client, supporting polymorphic owners and unique keys. It also adds a \pending\_input\ column to the existing \ruby\_llm\_tool\_calls\ table, using \jsonb\ for PostgreSQL and \json\ for other database adapters, to support new tool call input handling.

_lib/generators/ruby\llm/upgrade · high confidence

The chat UI generator now includes dedicated partials for rendering tool results, ensuring consistent presentation across both Tailwind and default CSS themes. These new templates handle both successful outputs and errors: if a tool execution fails, a specific error view is rendered; otherwise, the result is displayed in a styled container showing the tool's content (or a placeholder if empty) and the creation timestamp. This change ensures that generated applications have a robust, user-friendly way to view tool interactions, addressing previous issues with duplicate DOM IDs and inconsistent styling.

_lib/generators/ruby\_llm/chat\_ui/templates/tailwind/views/messages/tool\_results, lib/generators/ruby\_llm/chat\_ui/templates/views/messages/tool\results · high confidence

The install generator templates have been updated to reflect the RubyLLM 2.0 data model and configuration. The new schema includes dedicated tables for models, chats, messages, tool calls, MCP credentials, usage ledgers, and batches, with support for PostgreSQL JSONB and MySQL JSON types. Message models now include fields for caching, thinking text, citations, and raw content, while chat models support cancellation. The generator also creates a simplified initializer template for API key configuration and updates the message model to optionally include ActiveStorage attachments.

_lib/generators/ruby\llm/install/templates · high confidence

The generated chat UI now uses new default partials for rendering tool calls, available for both Tailwind and standard CSS styling. These templates display the tool name, arguments, and timestamp within a styled container, ensuring consistent presentation of tool interactions in the chat interface.

_lib/generators/ruby\_llm/chat\_ui/templates/tailwind/views/messages/tool\_calls, lib/generators/ruby\_llm/chat\_ui/templates/views/messages/tool\calls · high confidence

Added MCP conformance test client and failure expectations; Added MCP server fixture for testing; Added a dummy Rails application for integration testing; Added fixture templates for chat UI generation tests; Added test coverage for Rails integration and usage tracking; Added test coverage for model catalog, registry, and release workflows; Added test suite for gemspec constraints, logger configuration, and signed media URL sanitization; Added text and CSV fixture files for testing; Centralized test infrastructure and provider coverage matrix.

The gemfiles have been updated to include a new appraisal configuration for Rails 8.1 (specifically \~\> 8.1.4), extending the library's compatibility matrix alongside existing support for Rails 7.1, 7.2, and 8.0. This change also adjusts the \json\ gem constraint for the Rails 8.1 target to allow version 3 (\>= 3, \< 4), whereas earlier Rails versions remain pinned below version 3, ensuring compatibility with the specific dependency requirements of each Rails release.

gemfiles · high confidence

The gem's runtime dependencies have been significantly refactored for the 2.0 release: \zeitwerk\ is now pinned to \\~\> 2\, \faraday\ constraints have been adjusted (allowing \\>= 1.10.0\ via environment variable or defaulting to that range), and new dependencies including \base64\, \event\_stream\_parser\, \faraday-net\_http\, \faraday-retry\, \marcel\, and \schematist\ have been added. The \activesupport\ and \activerecord\ dependencies are now explicitly optional, and the minimum required Ruby version has been raised to 3.1.3. Additionally, the project structure now includes dedicated Gemfiles for the main library, documentation site, and a dummy Rails application used for integration testing, replacing previous ad-hoc dependency management.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 64 → 61 (-2.2)
• Rubric changed (rubric-2026.09.8 → rubric-2026.09.16) — scores are not directly comparable.

• Code Health 95 → 93 (-1.6)
• Architecture 97 → 73 (-23.8)
• Maturity 67 → 67 (+0.0)
• Readiness 62 → 61 (-0.9)
• Security 53 → 53 (-0.5)
• Domain Modelling 100 → 100 (+0.0)
• Accessibility 80 (new)
• Performance 100 (new)

• Change coupling: agent.rb ↔ chat.rb (lib/ruby_llm/agent.rb)
• Chat.render_payload (cognitive 16) (lib/ruby_llm/protocols/responses/chat.rb)
• Chat.render_payload (cyclomatic 16) (lib/ruby_llm/protocols/responses/chat.rb)
• Documentation: contradicts the code (docs/_reference/upgrading.md)
• Documentation: no installation or build instructions
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples
• Documentation: written for insiders (docs/about.md)
• Duplicated block (11–12 lines × 3) (lib/ruby_llm/image.rb)
• Duplicated block (12 lines × 2) (lib/ruby_llm/providers/azure/media.rb)
• Duplicated block (13 lines × 2) (lib/ruby_llm/ocr.rb)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Hotspot: docs/assets/js/provider-coverage.js (docs/assets/js/provider-coverage.js)
• Hotspot: lib/ruby_llm/protocols/responses/chat.rb (lib/ruby_llm/protocols/responses/chat.rb)
• Hotspot: lib/ruby_llm/providers/vertexai/models.rb (lib/ruby_llm/providers/vertexai/models.rb)
• Secret exported as workflow-level env
• …and 1 more

• Ambiguous overlap between token counting and tokenization. count_tokens clearly returns a count, but tokenize is ambiguous: it could return the list of tokens (tokenization) or the count (counting). Given count_tokens exists, tokenize likely does the former, but the naming convention is inconsistent with the 'count' verb used elsewhere.
• Documentation: no architecture or design documentation (docs/_core_features/chat.md)
• Documentation: no project overview (docs/_advanced/memory.md)
• Documentation: no project overview (docs/_advanced/rails-advanced-config.md)
• Documentation: no project overview (docs/_core_features/chat.md)
• Duplicated block (11–12 lines × 3) (lib/ruby_llm/image.rb)
• Duplicated block (13 lines × 2) (lib/ruby_llm/ocr.rb)
• FileTooLong: active_record/chat_methods.rb (lib/ruby_llm/active_record/chat_methods.rb)
• FileTooLong: ruby_llm/agent.rb (lib/ruby_llm/agent.rb)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Hotspot: docs/assets/js/homepage.js (docs/assets/js/homepage.js)
• Inconsistent factory method naming for creating distinct execution contexts. chat() creates a Chat context, workflow() creates a Workflow context, but mcp() creates an MCP context. While the domains are distinct, the pattern is inconsistent: chat and workflow are nouns describing the entity, while mcp is an acronym for the protocol. Furthermore, RubyLLM.Generators.Provider.CLI uses run and parse_options which are standard, but the main API uses varied verbs/nouns.
• …and 9 more

• 103 commits — 97 feature/other, 6 fixes

• lib/ruby_llm — 35 commits
• spec/ruby_llm — 13 commits
• lib/generators — 9 commits
• .github/workflows — 7 commits
• spec/fixtures — 7 commits
• (root) — 6 commits
• docs/_reference — 5 commits
• docs/assets — 4 commits
• docs/bin — 4 commits
• .github/triage.yml — 3 commits
• docs/index.md — 2 commits
• spec/support — 2 commits
• (repo) — 1 commit
• docs/_config.yml — 1 commit
• docs/_core_features — 1 commit
• docs/_getting_started — 1 commit
• docs/_plugins — 1 commit
• spec/docs — 1 commit

• fix: Fix DeepSeek image attachments in Chat Completions (#972)
• fix: Fix codecov.yml comment setting
• fix: Homepage mobile fixes
• fix: Isolate the Chat UI argument regression fixture
• fix: Polish the homepage and fix 1.x page copying
• fix: Refresh release cassettes and fix disabled tools
• change: Add Attachment#url_or_data_uri for inline references (#976)
• change: Add RubyLLM Skills to the ecosystem catalog
• change: Add What's New in 2.1 (#966)
• change: Add a Hetzner Inference provider
• change: Add a built-in MCP client (#959)
• change: Add detached open-report triage backlog
• change: Add resolution: to attachments (#989)
• change: Add typed judgments with TypeSafe Jev
• change: Align README with the homepage and expose Codex skill
• change: Allow JSON 3 while preserving Faraday compatibility (#968)
• change: Allow RubyLLM records to share a secondary database
• change: Apply account repository policy (#954)
• change: Apply account repository policy (#997)
• change: Assess human follow-ups with Copilot Triage
• …and 83 more

• Unchanged — 0 containers · 1 contexts · 0 edges

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

crmne/ruby_llm was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.