Rails Integration

RobotLab integrates seamlessly with Ruby on Rails applications.

Installation

Generate Files

rails generate robot_lab:install

This creates:

config/initializers/robot_lab.rb  # Logger setup
db/migrate/*_create_robot_lab_tables.rb  # Database tables
app/models/robot_lab_thread.rb  # Thread model
app/models/robot_lab_result.rb  # Result model
app/jobs/robot_run_job.rb  # Background job for robot execution
app/robots/  # Directory for robots
app/tools/   # Directory for tools

Options:

• --skip-migration — Skip database migration generation
• --skip-job — Skip background job generation

Run Migrations

rails db:migrate

Configuration

RobotLab uses MywayConfig for static configuration. Settings are loaded from YAML files and environment variables in the following priority order:

1. Bundled defaults (lib/robot_lab/config/defaults.yml)
2. Environment-specific overrides (development, test, production sections)
3. XDG user config (~/.config/robot_lab/config.yml)
4. Project config (./config/robot_lab.yml)
5. Environment variables (ROBOT_LAB_* prefix)

Project Config File

config/robot_lab.yml

defaults:
  ruby_llm:
    anthropic_api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
    openai_api_key: <%= ENV['OPENAI_API_KEY'] %>
    model: claude-sonnet-4
    request_timeout: 180

  # Template path auto-detected as app/prompts in Rails
  # template_path: app/prompts

development:
  ruby_llm:
    model: claude-haiku-3
    log_level: :debug

test:
  streaming_enabled: false
  ruby_llm:
    model: claude-3-haiku-20240307
    request_timeout: 30

production:
  ruby_llm:
    request_timeout: 180
    max_retries: 5

Environment Variables

Environment variables use the ROBOT_LAB_ prefix with double underscores for nested keys:

ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=180

RobotLab also falls back to standard provider environment variables (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY) when the prefixed versions are not set.

Initializer

Use RobotLab.configure to set runtime attributes. The generated initializer wires the logger to Rails.logger:

config/initializers/robot_lab.rb

# frozen_string_literal: true

RobotLab.configure do |c|
  c.logger = Rails.logger
end

You can also assign it directly if you prefer a one-liner:

RobotLab.config.logger = Rails.logger

Accessing Configuration

# Read configuration values
RobotLab.config.ruby_llm.model             #=> "claude-sonnet-4"
RobotLab.config.ruby_llm.anthropic_api_key #=> "sk-ant-..."
RobotLab.config.ruby_llm.request_timeout   #=> 120
RobotLab.config.streaming_enabled          #=> true

Creating Robots

Robot Generator

rails generate robot_lab:robot Support
rails generate robot_lab:robot Billing --description="Handles billing inquiries"
rails generate robot_lab:robot Router --routing

Robot Class

Robots are plain Ruby classes with a .build factory method that calls RobotLab.build with keyword arguments:

app/robots/support_robot.rb

# frozen_string_literal: true

class SupportRobot
  def self.build(**options)
    RobotLab.build(
      name: "support",
      description: "Handles customer support inquiries",
      system_prompt: "You are a helpful support assistant.",
      model: "claude-sonnet-4",
      local_tools: [OrderLookup],
      **options
    )
  end
end

Routing Robot Class

A routing robot classifies requests and activates optional tasks in a Network. It subclasses RobotLab::Robot and overrides call(result):

app/robots/classifier_robot.rb

# frozen_string_literal: true

class ClassifierRobot < RobotLab::Robot
  SYSTEM_PROMPT = <<~PROMPT
    You are a routing robot that classifies user requests.

    Analyze the user's request and respond with ONLY the category name.
    Valid categories: billing, technical, general
  PROMPT

  def self.build(**options)
    new(
      name: "classifier",
      description: "Classifies support requests",
      system_prompt: SYSTEM_PROMPT,
      **options
    )
  end

  def call(result)
    context = extract_run_context(result)
    message = context.delete(:message)

    robot_result = run(message, **context)

    new_result = result
      .with_context(@name.to_sym, robot_result)
      .continue(robot_result)

    category = robot_result.last_text_content.to_s.strip.downcase

    case category
    when /billing/  then new_result.activate(:billing)
    when /technical/ then new_result.activate(:technical)
    else new_result.activate(:general)
    end
  end
end

Use the routing robot as the first task in a network:

classifier = ClassifierRobot.build
billing    = BillingRobot.build
technical  = TechnicalRobot.build

network = RobotLab.create_network(name: "support") do
  task :classifier, classifier, depends_on: :none
  task :billing,    billing,    depends_on: :optional
  task :technical,  technical,  depends_on: :optional
end

result = network.run(message: "I was charged twice")

Custom Tool

Tools subclass RobotLab::Tool (which extends RubyLLM::Tool):

app/tools/order_lookup.rb

# frozen_string_literal: true

class OrderLookup < RobotLab::Tool
  description "Look up an order by ID"
  param :order_id, type: "string", desc: "The order ID to look up"

  def execute(order_id:)
    order = Order.find_by(id: order_id)
    return "Order not found" unless order

    {
      id: order.id,
      status: order.status,
      total: order.total.to_s,
      created_at: order.created_at.iso8601
    }.to_json
  end
end

Using in Controllers

app/controllers/chat_controller.rb

class ChatController < ApplicationController
  def create
    robot = SupportRobot.build
    result = robot.run(params[:message])

    render json: {
      response: result.last_text_content,
      robot_name: result.robot_name
    }
  end
end

Using a Network in Controllers

Networks use RobotLab.create_network with a block DSL that defines tasks. Each task wraps a robot with dependency declarations:

app/controllers/chat_controller.rb

class ChatController < ApplicationController
  def create
    support_robot  = SupportRobot.build
    billing_robot  = BillingRobot.build

    network = RobotLab.create_network(name: "customer_service") do
      task :support, support_robot, depends_on: :none
      task :billing, billing_robot, depends_on: :optional
    end

    result = network.run(message: params[:message], user_id: current_user.id)

    # result is a SimpleFlow::Result
    # result.value is a RobotResult from the last robot
    render json: {
      response: result.value.last_text_content,
      robot_name: result.value.robot_name
    }
  end
end

Prompt Templates

Template Location

Templates are .md files with YAML front matter, stored in app/prompts/ (auto-configured for Rails):

app/prompts/
├── support.md
├── billing.md
└── router.md

Template Format

app/prompts/support.md

---
description: Customer support assistant
parameters:
  company_name: null
  tone: friendly
model: claude-sonnet-4
temperature: 0.7
---
You are a support agent for <%= company_name %>.
Respond in a <%= tone %> manner.

Your responsibilities:
- Answer product questions
- Help with order issues
- Provide friendly assistance

Template Usage

# Pass context to fill template parameters
robot = RobotLab.build(
  name: "support",
  template: :support,
  context: { company_name: "Acme Corp" }
)

# Parameters with defaults (like `tone: friendly`) are optional.
# Parameters set to null are required and must be provided via context.
result = robot.run("I need help with my order")

Action Cable Integration

Channel

app/channels/chat_channel.rb

class ChatChannel < ApplicationCable::Channel
  def subscribed
    stream_from "chat_#{params[:session_id]}"
  end

  def receive(data)
    message    = data["message"]
    session_id = data["session_id"]

    robot  = SupportRobot.build
    result = robot.run(message)

    ActionCable.server.broadcast(
      "chat_#{session_id}",
      {
        event: "complete",
        response: result.last_text_content,
        robot_name: result.robot_name
      }
    )
  end
end

JavaScript Client

const channel = consumer.subscriptions.create(
  { channel: "ChatChannel", session_id: sessionId },
  {
    received(data) {
      if (data.event === "complete") {
        displayMessage(data.response);
      }
    }
  }
);

channel.send({ message: "Hello!", session_id: sessionId });

Background Jobs

RobotLab::Job Base Class

All RobotLab background jobs inherit from RobotLab::Job (RobotLab::RailsIntegration::Job), which handles the full robot-run lifecycle automatically:

1. Resolves the robot class (from the robot_class DSL or a robot_class: kwarg at enqueue time)
2. Finds or creates a RobotLabThread record and stamps the incoming message
3. Wires Turbo Stream callbacks when turbo-rails is available (graceful no-op otherwise)
4. Runs the robot and persists the RobotResult to RobotLabResult
5. Broadcasts a completion or error event via Turbo Streams

retry_on StandardError (3 attempts, 5 s wait) and discard_on ActiveJob::DeserializationError are configured by default.

RobotRunJob (Generated)

The install generator creates a thin subclass you can enqueue with any robot class at runtime:

app/jobs/robot_run_job.rb

class RobotRunJob < RobotLab::Job
  queue_as :default
end

# Enqueue from a controller — pass robot_class: as a string
RobotRunJob.perform_later(
  robot_class: "SupportRobot",
  message:     params[:message],
  thread_id:   session_id
)

render json: { status: "processing" }

Dedicated Job (robot_class DSL)

Generate a job pre-bound to a specific robot class so callers never need to pass robot_class::

rails generate robot_lab:job Support            # binds to SupportRobot, queue: default
rails generate robot_lab:job Support --queue ai # custom queue name

app/jobs/support_job.rb

class SupportJob < RobotLab::Job
  queue_as :default
  robot_class SupportRobot
end

# No robot_class: needed at enqueue time
SupportJob.perform_later(message: params[:message], thread_id: session_id)

The robot_class DSL is per-subclass and does not affect sibling job classes.

Omitting thread_id (fire-and-forget)

When thread_id is omitted the job runs the robot and returns the result without any persistence or broadcasting:

RobotRunJob.perform_later(robot_class: "ChatRobot", message: "ping")

Turbo Stream Token Streaming

When turbo-rails is installed, RobotLab::Job automatically streams content tokens and tool call badges to the browser in real time.

View Setup

Subscribe to the thread's Turbo Stream channel in your view:

<%%= turbo_stream_from "robot_lab_thread_#{@thread_id}" %>

<div id="robot_response"></div>
<div id="robot_tools"></div>
<div id="robot_status">Processing...</div>
<div id="robot_errors"></div>

As the robot generates tokens, they are appended to #robot_response. Tool calls appear as badges in #robot_tools. On completion, #robot_status is replaced with "Complete".

TurboStreamCallbacks API

RobotLab::RailsIntegration::TurboStreamCallbacks is a stateless utility module for building callback Procs. Use it outside of RobotRunJob for custom streaming setups:

# Check if Turbo Streams is available
RobotLab::RailsIntegration::TurboStreamCallbacks.available?

# Build a content streaming callback
on_content = RobotLab::RailsIntegration::TurboStreamCallbacks.build_content_callback(
  stream_name: "robot_lab_thread_#{thread_id}",
  target: "robot_response"  # default
)

# Build a tool call badge callback
on_tool_call = RobotLab::RailsIntegration::TurboStreamCallbacks.build_tool_call_callback(
  stream_name: "robot_lab_thread_#{thread_id}",
  target: "robot_tools"  # default
)

# Wire into a robot at build time
robot = SupportRobot.build(on_content: on_content, on_tool_call: on_tool_call)
robot.run(message)

The stream name convention is "robot_lab_thread_#{thread_id}", matching the RobotLabThread.session_id pattern.

Custom Background Job

For full control outside of the RobotLab::Job lifecycle (e.g. custom persistence or a different broadcasting strategy), inherit from ApplicationJob directly:

app/jobs/process_message_job.rb

class ProcessMessageJob < ApplicationJob
  queue_as :default

  def perform(session_id:, message:, user_id:)
    robot  = SupportRobot.build
    result = robot.run(message)

    ActionCable.server.broadcast(
      "chat_#{session_id}",
      {
        event: "complete",
        response: result.last_text_content,
        robot_name: result.robot_name
      }
    )
  end
end

Testing

Test Configuration

Use config/robot_lab.yml to configure the test environment with a faster, cheaper model:

config/robot_lab.yml

test:
  max_iterations: 3
  streaming_enabled: false
  ruby_llm:
    model: claude-3-haiku-20240307
    request_timeout: 30
    max_retries: 1

Robot Tests

test/robots/support_robot_test.rb

require "test_helper"

class SupportRobotTest < ActiveSupport::TestCase
  test "builds valid robot" do
    robot = SupportRobot.build
    assert_equal "support", robot.name
  end

  test "robot has correct model" do
    robot = SupportRobot.build
    assert_equal "claude-sonnet-4", robot.model
  end

  test "robot has local tools" do
    robot = SupportRobot.build
    tool_names = robot.local_tools.map(&:name)
    assert_includes tool_names, "order_lookup"
  end
end

Integration Tests

test/integration/chat_test.rb

require "test_helper"

class ChatTest < ActionDispatch::IntegrationTest
  test "processes chat message" do
    VCR.use_cassette("chat_response") do
      post chat_path, params: { message: "Hello" }
      assert_response :success

      json = JSON.parse(response.body)
      assert json["response"].present?
    end
  end
end

Models

Thread Model

app/models/robot_lab_thread.rb

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
end

Result Model

app/models/robot_lab_result.rb

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

  default_scope { order(sequence_number: :asc) }

  def to_robot_result
    RobotLab::RobotResult.new(
      robot_name: robot_name,
      output: (output_data || []).map { |d| RobotLab::Message.from_hash(d.symbolize_keys) },
      tool_calls: (tool_calls_data || []).map { |d| RobotLab::Message.from_hash(d.symbolize_keys) },
      stop_reason: stop_reason
    )
  end
end

Best Practices

1. Use Service Objects

app/services/chat_service.rb

class ChatService
  def initialize(user:)
    @user = user
  end

  def process(message)
    robot  = SupportRobot.build
    result = robot.run(message)

    {
      response: result.last_text_content,
      robot_name: result.robot_name
    }
  end

  def process_with_network(message)
    support_robot = SupportRobot.build
    billing_robot = BillingRobot.build

    network = RobotLab.create_network(name: "customer_service") do
      task :support, support_robot, depends_on: :none
      task :billing, billing_robot, depends_on: :optional
    end

    result = network.run(message: message, user_id: @user.id)

    {
      response: result.value.last_text_content,
      robot_name: result.value.robot_name
    }
  end
end

2. Handle Errors

def create
  result = ChatService.new(user: current_user).process(params[:message])
  render json: result
rescue RobotLab::Error => e
  render json: { error: e.message }, status: :unprocessable_entity
rescue StandardError => e
  Rails.logger.error("Chat error: #{e.message}")
  render json: { error: "An error occurred" }, status: :internal_server_error
end

3. Rate Limiting

class ChatController < ApplicationController
  before_action :check_rate_limit

  private

  def check_rate_limit
    key = "chat_rate:#{current_user.id}"
    count = Rails.cache.increment(key, 1, expires_in: 1.minute)

    if count > 10
      render json: { error: "Rate limit exceeded" }, status: :too_many_requests
    end
  end
end

Next Steps

• Building Robots - Robot patterns
• Creating Networks - Network configuration