layered-assistant-rails

An open source Rails 8+ engine built on layered-ui-rails that provides a multi-provider AI assistant with streaming responses and a full conversation UI.

• Ruby >= 3.2.0
• Ruby on Rails >= 8.0
• layered-ui-rails installed in the host app

Add to your Gemfile:

gem "layered-assistant-rails"

Then run:

bundle install

Run the install generator to copy CSS and register imports:

bin/rails generate layered:assistant:install

This will:

• Copy layered_ui.css to app/assets/tailwind/
• Add @import "./layered_ui"; to your application.css
• Add import "layered_ui" to your application.js
• Copy layered_assistant.css to app/assets/tailwind/layered_assistant.css
• Add @import "./layered_assistant"; to your app/assets/tailwind/application.css (after the layered-ui import)
• Add import "layered_assistant" to your app/javascript/application.js (after the layered-ui import)
• Mount the engine at /layered/assistant in your config/routes.rb
• Copy engine migrations into your application

All steps are idempotent - re-running the generator will not duplicate imports, routes, or migrations.

After updating the gem, copy any new migrations and run them:

bin/rails generate layered:assistant:migrations
bin/rails db:migrate

All non-public engine routes are blocked by default (403 Forbidden) until you configure an authorize block. The install generator creates a starter initialiser at config/initializers/layered_assistant.rb - uncomment one of the examples to get started.

Once configured, visit /layered/assistant (or wherever you mounted the engine) to verify access.

Layered::Assistant.authorize do
  # No-op: all requests permitted
end

Layered::Assistant.authorize do
  redirect_to main_app.new_user_session_path unless user_signed_in?
end

Layered::Assistant.authorize do
  head :forbidden unless current_user&.admin?
end

The block runs in controller context, so you have access to request, current_user, redirect_to, head, main_app, and all other controller methods.

The l_assistant_accessible? helper evaluates the authorize block without side effects. Use it to conditionally show navigation or links to the engine:

<% if l_assistant_accessible? %>
  <%= link_to "Assistant", layered_assistant.root_path %>
<% end %>

The engine provides two convenience helpers for wiring the layered-ui panel to the assistant. Use them inside content_for blocks in your application layout:

<% content_for :l_ui_panel_heading do %>
  <%= layered_assistant_panel_header %>
<% end %>

<% content_for :l_ui_panel_body do %>
  <%= layered_assistant_panel_body %>
<% end %>

<%= render template: "layouts/layered_ui/application" %>

Both helpers accept keyword arguments that are forwarded as HTML attributes to the underlying turbo_frame_tag:

<%= layered_assistant_panel_body data: { controller: "panel" } %>

A dummy Rails app is included for development and testing:

cd test/dummy
bin/setup
bin/dev

Then visit http://localhost:3000.

The dummy app can be deployed with Kamal. Set the required environment variables and deploy from test/dummy:

cd test/dummy
export KAMAL_DEPLOY_IP=<server-ip>
export KAMAL_DEPLOY_DOMAIN=<domain>
export KAMAL_SSH_KEY=<path-to-ssh-key>
kamal deploy

Run the gem tests from the root directory:

bundle exec rake test

Released under the Apache 2.0 License.

Copyright 2026 LAYERED AI LIMITED (UK company number: 17056830). See NOTICE for attribution details.

The source code is fully open, but the layered.ai name, logo, and brand assets are trademarks of LAYERED AI LIMITED. The Apache 2.0 license does not grant rights to use the layered.ai branding. Forks and redistributions must use a distinct name. See TRADEMARK.md for the full policy.

• CLA.md - contributor license agreement