robot_lab-rails 0.1.0

data/docs/index.md

@@ -0,0 +1,75 @@
+# robot_lab-rails
+
+Rails integration for the [RobotLab](https://github.com/MadBomber/robot_lab) LLM agent framework.
+
+> [!CAUTION]
+> This gem is under active development. APIs may change without notice.
+
+## What it provides
+
+- **Rails Engine** — autoloads `app/robots/` and `app/tools/` in your application
+- **Railtie** — wires `RobotLab.config` to `Rails.logger` and applies Rails-specific configuration
+- **`RobotLab::Job`** — ActiveJob base class with Turbo Stream streaming, thread persistence, and error broadcasting
+- **Generators** — `rails generate robot_lab:install`, `robot_lab:robot NAME`, `robot_lab:job NAME`
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "robot_lab"
+gem "robot_lab-rails"
+```
+
+Then run the installer:
+
+```bash
+rails generate robot_lab:install
+rails db:migrate
+```
+
+## Quick Example
+
+```ruby
+# app/robots/support_robot.rb
+class SupportRobot
+  SYSTEM_PROMPT = "You are a helpful support assistant."
+
+  def self.build(**options)
+    RobotLab.build(
+      name: "support",
+      system_prompt: SYSTEM_PROMPT,
+      **options
+    )
+  end
+end
+
+# app/jobs/support_robot_job.rb
+class SupportRobotJob < RobotLab::Job
+  queue_as :default
+  robot_class SupportRobot
+end
+
+# From a controller:
+SupportRobotJob.perform_later(
+  message:   params[:message],
+  thread_id: session[:id]
+)
+```
+
+## Turbo Stream Streaming
+
+When `thread_id:` is provided and `turbo-rails` is installed, streaming token output is broadcast automatically:
+
+```erb
+<%= turbo_stream_from "robot_lab_thread_#{session[:id]}" %>
+<div id="robot_response"></div>
+<div id="robot_status"></div>
+```
+
+## Links
+
+- [Rails Integration Guide](guides/rails-integration.md)
+- [Rails Application Example](examples/rails-application.md)
+- [RobotLab Core](https://github.com/MadBomber/robot_lab)
+- [RubyGems](https://rubygems.org/gems/robot_lab-rails)

data/examples/18_rails/.envrc

@@ -0,0 +1,3 @@
+source_up
+
+export RR=`pwd`

data/examples/18_rails/.gitignore

@@ -0,0 +1,5 @@
+db/*.sqlite3
+db/schema.rb
+log/
+tmp/
+Gemfile.lock

data/examples/18_rails/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "rails", "~> 8.0"
+gem "sqlite3", "~> 2.0"
+gem "puma", "~> 6.0"
+gem "turbo-rails", "~> 2.0"
+
+gem "robot_lab"
+gem "robot_lab-rails"

data/examples/18_rails/README.md

@@ -0,0 +1,48 @@
+# RobotLab Rails 8 Demo
+
+Minimal Rails 8 app that demonstrates RobotLab's full Rails integration:
+
+- **ChatRobot** with a custom `TimeTool`
+- **RobotRunJob** for background execution
+- **Turbo Stream** token streaming to the browser
+- **Persistence** via `RobotLabThread` + `RobotLabResult`
+- **Conversation history** on page reload
+
+## Prerequisites
+
+- Ruby 3.2+
+- An LLM API key (e.g. `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in your env)
+
+## Setup
+
+```bash
+cd examples/18_rails
+bin/setup
+```
+
+## Run
+
+```bash
+bin/dev
+# Open http://localhost:3000
+```
+
+## Try It
+
+1. Type "What time is it?" — the robot will call TimeTool and stream the response
+2. Refresh the page — conversation history is preserved
+3. Check `db/development.sqlite3` to see persisted threads and results
+
+## Architecture
+
+```
+app/
+  controllers/chat_controller.rb  — index + create actions
+  views/chat/index.html.erb       — form + Turbo Stream subscription
+  models/                         — RobotLabThread, RobotLabResult
+  robots/chat_robot.rb            — robot factory with system prompt + tool
+  tools/time_tool.rb              — simple RobotLab::Tool subclass
+  jobs/robot_run_job.rb           — enqueues robot.run() with Turbo callbacks
+```
+
+No Redis, no Solid Queue, no asset pipeline. Uses `:async` adapters for both ActiveJob and ActionCable.

data/examples/18_rails/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "config/application"
+Rails.application.load_tasks

data/examples/18_rails/app/controllers/application_controller.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationController < ActionController::Base
+end

data/examples/18_rails/app/controllers/chat_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class ChatController < ApplicationController
+  def index
+    @thread_id = session[:thread_id] ||= SecureRandom.uuid
+    thread = RobotLabThread.find_by(session_id: @thread_id)
+    @results = thread&.results&.to_a || []
+  end
+
+  def create
+    thread_id = session[:thread_id] ||= SecureRandom.uuid
+    message = params[:message].to_s.strip
+    return redirect_to root_path if message.empty?
+
+    # Persist user message so it appears in history on reload
+    thread = RobotLabThread.find_or_create_by_session_id(thread_id)
+    sequence = thread.results.maximum(:sequence_number).to_i + 1
+    thread.results.create!(
+      robot_name:      "user",
+      sequence_number: sequence,
+      output_data:     [{ role: "user", content: message }],
+      tool_calls_data: [],
+      stop_reason:     "user_message",
+      checksum:        Digest::SHA256.hexdigest(message)
+    )
+
+    RobotRunJob.perform_later(
+      robot_class: "ChatRobot",
+      message:     message,
+      thread_id:   thread_id
+    )
+
+    respond_to do |format|
+      format.turbo_stream do
+        render turbo_stream: [
+          turbo_stream.append("messages", partial: "chat/user_message", locals: { message: message }),
+          turbo_stream.replace("robot_status", "<div id=\"robot_status\"><span class=\"thinking\">Thinking...</span></div>"),
+          turbo_stream.update("robot_response", ""),
+          turbo_stream.update("robot_tools", ""),
+          turbo_stream.update("robot_errors", "")
+        ]
+      end
+      format.html { redirect_to root_path }
+    end
+  end
+end

data/examples/18_rails/app/jobs/application_job.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationJob < ActiveJob::Base
+end

data/examples/18_rails/app/jobs/robot_run_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Generic background job for executing any robot asynchronously.
+#
+# Inherits from RobotLab::Job — Turbo Stream wiring, thread persistence,
+# and completion/error broadcasting are all handled by the base class.
+#
+# Pass robot_class: at enqueue time to select which robot to run.
+#
+# @example Enqueue from a controller
+#   RobotRunJob.perform_later(
+#     robot_class: "ChatRobot",
+#     message:     params[:message],
+#     thread_id:   session_id
+#   )
+#
+class RobotRunJob < RobotLab::Job
+  queue_as :default
+end

data/examples/18_rails/app/models/application_record.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+end

data/examples/18_rails/app/models/robot_lab_result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class RobotLabResult < ApplicationRecord
+  belongs_to :thread,
+             class_name: "RobotLabThread",
+             foreign_key: :session_id,
+             primary_key: :session_id
+
+  validates :session_id, presence: true
+  validates :robot_name, presence: true
+  validates :sequence_number, presence: true,
+                              numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+
+  default_scope { order(sequence_number: :asc) }
+
+  def output_messages
+    (output_data || []).map do |data|
+      RobotLab::Message.from_hash(data.symbolize_keys)
+    end
+  end
+
+  def tool_call_messages
+    (tool_calls_data || []).map do |data|
+      RobotLab::Message.from_hash(data.symbolize_keys)
+    end
+  end
+
+  def to_robot_result
+    RobotLab::RobotResult.new(
+      robot_name: robot_name,
+      output: output_messages,
+      tool_calls: tool_call_messages,
+      stop_reason: stop_reason
+    )
+  end
+end

data/examples/18_rails/app/models/robot_lab_thread.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class RobotLabThread < ApplicationRecord
+  has_many :results,
+           class_name: "RobotLabResult",
+           foreign_key: :session_id,
+           primary_key: :session_id,
+           dependent: :destroy
+
+  validates :session_id, presence: true, uniqueness: true
+
+  def self.find_or_create_by_session_id(id)
+    find_or_create_by(session_id: id)
+  end
+
+  def last_result
+    results.order(sequence_number: :desc).first
+  end
+
+  def message_count
+    results.count
+  end
+end

data/examples/18_rails/app/robots/chat_robot.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class ChatRobot
+  SYSTEM_PROMPT = "You are a friendly assistant. Be concise."
+
+  def self.build(**options)
+    RobotLab.build(
+      name: "chat",
+      system_prompt: SYSTEM_PROMPT,
+      local_tools: [TimeTool],
+      **options
+    )
+  end
+end

data/examples/18_rails/app/tools/time_tool.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class TimeTool < RobotLab::Tool
+  description "Get the current date and time"
+
+  def execute
+    Time.current.strftime("%Y-%m-%d %H:%M:%S %Z")
+  end
+end

data/examples/18_rails/app/views/chat/_user_message.html.erb

@@ -0,0 +1 @@
+<div class="message user"><%= message %></div>

data/examples/18_rails/app/views/chat/index.html.erb

@@ -0,0 +1,67 @@
+<h1>RobotLab Chat</h1>
+
+<%= turbo_stream_from "robot_lab_thread_#{@thread_id}" %>
+
+<%= form_with url: chat_path, method: :post, class: "chat-form" do |f| %>
+  <%= f.text_field :message, placeholder: "Type a message...", autofocus: true, autocomplete: "off" %>
+  <%= f.submit "Send" %>
+<% end %>
+
+<div id="chat-scroll">
+  <div id="messages">
+    <% @results.each do |result| %>
+      <% if result.robot_name == "user" %>
+        <% result.output_messages.each do |msg| %>
+          <div class="message user"><%= msg.content %></div>
+        <% end %>
+      <% else %>
+        <% result.output_messages.each do |msg| %>
+          <div class="message assistant"><%= msg.content %></div>
+        <% end %>
+        <% unless result.tool_call_messages.empty? %>
+          <div>
+            <% result.tool_call_messages.each do |tc| %>
+              <span class="tool-badge">Used: <%= tc.content %></span>
+            <% end %>
+          </div>
+        <% end %>
+      <% end %>
+    <% end %>
+  </div>
+
+  <div id="robot_tools"></div>
+  <div id="robot_response" class="message assistant" style="display:none;"></div>
+  <div id="robot_errors"></div>
+  <div id="robot_status"></div>
+</div>
+
+<script>
+  const scrollContainer = document.getElementById('chat-scroll');
+  const responseEl = document.getElementById('robot_response');
+
+  function scrollToBottom() {
+    scrollContainer.scrollTop = scrollContainer.scrollHeight;
+  }
+
+  // Auto-scroll on any mutation inside the scroll container
+  const observer = new MutationObserver(function() {
+    if (responseEl.textContent.trim().length > 0) {
+      responseEl.style.display = 'block';
+    }
+    scrollToBottom();
+  });
+
+  observer.observe(scrollContainer, { childList: true, characterData: true, subtree: true });
+
+  // Clear the input field after form submission
+  document.addEventListener('turbo:submit-end', function(event) {
+    const input = event.target.querySelector('input[name="message"]');
+    if (input) {
+      input.value = '';
+      input.focus();
+    }
+  });
+
+  // Scroll to bottom on initial load if there's history
+  scrollToBottom();
+</script>

data/examples/18_rails/app/views/layouts/application.html.erb

@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>RobotLab Rails Demo</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <%= action_cable_meta_tag %>
+  <script type="importmap">
+  {
+    "imports": {
+      "@hotwired/turbo": "https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.12/+esm",
+      "@hotwired/turbo-rails": "https://cdn.jsdelivr.net/npm/@hotwired/turbo-rails@8.0.12/+esm",
+      "@rails/actioncable": "https://cdn.jsdelivr.net/npm/@rails/actioncable@8.0.200/+esm"
+    }
+  }
+  </script>
+  <script type="module">
+    import "@hotwired/turbo-rails"
+  </script>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: system-ui, -apple-system, sans-serif; background: #1a1a2e; color: #e0e0e0; height: 100vh; display: flex; flex-direction: column; align-items: center; overflow: hidden; }
+    .container { max-width: 720px; width: 100%; padding: 2rem 1rem; display: flex; flex-direction: column; height: 100%; overflow: hidden; }
+    #chat-scroll { flex: 1; overflow-y: auto; scroll-behavior: smooth; padding-right: 0.25rem; }
+    #chat-scroll::-webkit-scrollbar { width: 6px; }
+    #chat-scroll::-webkit-scrollbar-track { background: transparent; }
+    #chat-scroll::-webkit-scrollbar-thumb { background: #333; border-radius: 3px; }
+    h1 { color: #7c83ff; margin-bottom: 1.5rem; font-size: 1.5rem; }
+    .chat-form { display: flex; gap: 0.5rem; margin-bottom: 1.5rem; }
+    .chat-form input[type="text"] { flex: 1; padding: 0.75rem; border-radius: 8px; border: 1px solid #333; background: #16213e; color: #e0e0e0; font-size: 1rem; }
+    .chat-form input[type="text"]:focus { outline: none; border-color: #7c83ff; }
+    .chat-form button { padding: 0.75rem 1.5rem; border-radius: 8px; border: none; background: #7c83ff; color: #fff; font-size: 1rem; cursor: pointer; }
+    .chat-form button:hover { background: #6a70e0; }
+    .message { padding: 0.75rem 1rem; margin-bottom: 0.5rem; border-radius: 8px; line-height: 1.5; white-space: pre-wrap; }
+    .message.user { background: #1f4068; margin-left: 4rem; }
+    .message.assistant { background: #16213e; margin-right: 4rem; border: 1px solid #2a2a4a; }
+    .tool-badge { display: inline-block; background: #2d1b69; color: #b8b0ff; padding: 0.2rem 0.6rem; border-radius: 4px; font-size: 0.8rem; margin: 0.25rem 0.25rem 0.25rem 0; }
+    .thinking { color: #7c83ff; font-style: italic; }
+    .complete { color: #4ade80; font-size: 0.85rem; }
+    .error { color: #f87171; background: #2d1320; padding: 0.5rem 0.75rem; border-radius: 6px; margin-bottom: 0.5rem; }
+    #robot_response { white-space: pre-wrap; }
+    .history-label { color: #666; font-size: 0.75rem; text-transform: uppercase; margin-bottom: 0.75rem; letter-spacing: 0.05em; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <%= yield %>
+  </div>
+</body>
+</html>

data/examples/18_rails/bin/dev

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+echo "Starting Puma on http://localhost:3000 ..."
+bundle exec rails server -p 3000

data/examples/18_rails/bin/rails

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+APP_PATH = File.expand_path("../config/application", __dir__)
+require_relative "../config/application"
+require "rails/commands"

data/examples/18_rails/bin/setup

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+echo "==> Installing gems..."
+bundle install
+
+echo "==> Creating database..."
+bundle exec rails db:create
+
+echo "==> Running migrations..."
+bundle exec rails db:migrate
+
+echo "==> Done! Run bin/dev to start the server."

data/examples/18_rails/config/application.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+require "rails"
+require "active_record/railtie"
+require "active_job/railtie"
+require "action_controller/railtie"
+require "action_view/railtie"
+require "action_cable/engine"
+
+Bundler.require(*Rails.groups)
+
+module RobotLabDemo
+  class Application < Rails::Application
+    config.load_defaults 8.0
+
+    config.eager_load = false
+    config.consider_all_requests_local = true
+    config.secret_key_base = "demo-secret-key-for-development-only"
+
+    # Use async adapter for jobs — no external process needed
+    config.active_job.queue_adapter = :async
+
+    # Autoload app/robots and app/tools
+    config.autoload_paths << root.join("app", "robots")
+    config.autoload_paths << root.join("app", "tools")
+
+    # Disable unused middleware
+    config.api_only = false
+    config.hosts.clear
+  end
+end

data/examples/18_rails/config/cable.yml

@@ -0,0 +1,2 @@
+development:
+  adapter: async

data/examples/18_rails/config/database.yml

@@ -0,0 +1,5 @@
+development:
+  adapter: sqlite3
+  database: db/development.sqlite3
+  pool: 5
+  timeout: 5000

data/examples/18_rails/config/environment.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "application"
+Rails.application.initialize!

data/examples/18_rails/config/initializers/robot_lab.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+RobotLab.config.logger = Rails.logger

data/examples/18_rails/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  root "chat#index"
+  post "chat", to: "chat#create"
+end

data/examples/18_rails/config.ru

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "config/environment"
+run Rails.application

data/examples/18_rails/db/migrate/001_create_robot_lab_tables.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class CreateRobotLabTables < ActiveRecord::Migration[7.0]
+  def change
+    create_table :robot_lab_threads do |t|
+      t.string :session_id, null: false, index: { unique: true }
+      t.text :initial_input
+      t.json :input_metadata, default: {}
+      t.json :state_data, default: {}
+      t.text :last_user_message
+      t.datetime :last_user_message_at
+
+      t.timestamps
+    end
+
+    create_table :robot_lab_results do |t|
+      t.string :session_id, null: false, index: true
+      t.string :robot_name, null: false
+      t.integer :sequence_number, null: false, default: 0
+      t.json :output_data, default: []
+      t.json :tool_calls_data, default: []
+      t.string :stop_reason
+      t.string :checksum
+
+      t.timestamps
+    end
+
+    add_index :robot_lab_results, [:session_id, :sequence_number]
+    add_foreign_key :robot_lab_results, :robot_lab_threads,
+                    column: :session_id, primary_key: :session_id
+  end
+end

data/lib/generators/robot_lab/install_generator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RobotLab
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_migration, type: :boolean, default: false,
+                                    desc: "Skip database migration generation"
+      class_option :skip_job, type: :boolean, default: false,
+                              desc: "Skip background job generation"
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/robot_lab.rb"
+      end
+
+      def create_migration
+        return if options[:skip_migration]
+
+        migration_template "migration.rb.tt", "db/migrate/create_robot_lab_tables.rb"
+      end
+
+      def create_models
+        return if options[:skip_migration]
+
+        template "thread_model.rb.tt", "app/models/robot_lab_thread.rb"
+        template "result_model.rb.tt", "app/models/robot_lab_result.rb"
+      end
+
+      def create_job
+        return if options[:skip_job]
+
+        template "job.rb.tt", "app/jobs/robot_run_job.rb"
+      end
+
+      def create_directories
+        empty_directory "app/robots"
+        empty_directory "app/tools"
+      end
+
+      def display_post_install
+        say ""
+        say "RobotLab installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run migrations: rails db:migrate"
+        say "  2. Configure your LLM API keys in config/initializers/robot_lab.rb"
+        say "  3. Generate your first robot: rails g robot_lab:robot MyRobot"
+        say "  4. Enqueue robot runs via RobotRunJob (app/jobs/robot_run_job.rb)" unless options[:skip_job]
+        say ""
+      end
+    end
+  end
+end