robot_lab-rails 0.1.0

data/lib/generators/robot_lab/job_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RobotLab
+  module Generators
+    class JobGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :queue, type: :string, default: "default",
+                           desc: "ActiveJob queue name"
+
+      def create_job_file
+        template "robot_job.rb.tt", "app/jobs/#{file_name}_job.rb"
+      end
+
+      private
+
+      def queue_name
+        options[:queue]
+      end
+
+      def robot_class_name
+        "#{class_name}Robot"
+      end
+    end
+  end
+end

data/lib/generators/robot_lab/robot_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RobotLab
+  module Generators
+    class RobotGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :description, type: :string, default: nil,
+                                 desc: "Robot description"
+      class_option :routing, type: :boolean, default: false,
+                             desc: "Generate a routing robot"
+      class_option :tools, type: :array, default: [],
+                           desc: "List of tools to include"
+
+      def create_robot_file
+        if options[:routing]
+          template "routing_robot.rb.tt", "app/robots/#{file_name}_robot.rb"
+        else
+          template "robot.rb.tt", "app/robots/#{file_name}_robot.rb"
+        end
+      end
+
+      def create_test_file
+        template "robot_test.rb.tt", "test/robots/#{file_name}_robot_test.rb"
+      end
+
+      private
+
+      def robot_description
+        options[:description] || "A helpful #{class_name.titleize} robot"
+      end
+
+      def robot_tools
+        options[:tools]
+      end
+    end
+  end
+end

data/lib/generators/robot_lab/templates/initializer.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# RobotLab Configuration
+#
+# RobotLab uses MywayConfig for configuration. Settings are loaded from:
+#
+#   1. Bundled defaults (lib/robot_lab/config/defaults.yml)
+#   2. Environment-specific overrides (development, test, production)
+#   3. XDG user config (~/.config/robot_lab/config.yml)
+#   4. Project config (./config/robot_lab.yml)
+#   5. Environment variables (ROBOT_LAB_* prefix)
+#
+# Create config/robot_lab.yml for project-specific settings:
+#
+#   defaults:
+#     ruby_llm:
+#       anthropic_api_key: <%%= ENV['ANTHROPIC_API_KEY'] %>
+#       openai_api_key: <%%= ENV['OPENAI_API_KEY'] %>
+#       model: claude-sonnet-4
+#       request_timeout: 180
+#
+#   development:
+#     ruby_llm:
+#       log_level: :debug
+#
+#   test:
+#     streaming_enabled: false
+#     ruby_llm:
+#       model: claude-3-haiku-20240307
+#       request_timeout: 30
+#
+# Or use environment variables with double underscores for nested keys:
+#
+#   ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+#   ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
+#
+
+# Set the RobotLab logger to use Rails.logger
+RobotLab.config.logger = Rails.logger

data/lib/generators/robot_lab/templates/job.rb.tt

@@ -0,0 +1,21 @@
+# 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, or
+# generate a dedicated job with `rails generate robot_lab:job NAME` to
+# bind a job class to a specific robot via the robot_class DSL.
+#
+# @example Enqueue from a controller
+#   RobotRunJob.perform_later(
+#     robot_class: "SupportRobot",
+#     message:     params[:message],
+#     thread_id:   session_id
+#   )
+#
+class RobotRunJob < RobotLab::Job
+  queue_as :default
+end

data/lib/generators/robot_lab/templates/migration.rb.tt

@@ -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/templates/result_model.rb.tt

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# RobotLab Result Model
+#
+# Stores robot execution results for history persistence.
+#
+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/lib/generators/robot_lab/templates/robot.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# <%= class_name %> Robot
+#
+# <%= robot_description %>
+#
+class <%= class_name %>Robot
+  SYSTEM_PROMPT = <<~PROMPT
+    You are a helpful <%= class_name.titleize %> assistant.
+
+    Your role is to assist users with their requests in a friendly and efficient manner.
+  PROMPT
+
+  def self.build(**options)
+    RobotLab.build(
+      name: "<%= file_name %>",
+      description: "<%= robot_description %>",
+      system_prompt: SYSTEM_PROMPT,
+      local_tools: tools,
+      **options
+    )
+  end
+
+  def self.tools
+    [
+      <%- robot_tools.each do |tool| -%>
+      # <%= tool.camelize %>,
+      <%- end -%>
+    ]
+  end
+end

data/lib/generators/robot_lab/templates/robot_job.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Background job that runs <%= robot_class_name %> asynchronously.
+#
+# @example Enqueue from a controller
+#   <%= class_name %>Job.perform_later(
+#     message:   params[:message],
+#     thread_id: session_id
+#   )
+#
+class <%= class_name %>Job < RobotLab::Job
+  queue_as :<%= queue_name %>
+
+  robot_class <%= robot_class_name %>
+end

data/lib/generators/robot_lab/templates/robot_test.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class <%= class_name %>RobotTest < ActiveSupport::TestCase
+  def setup
+    @robot = <%= class_name %>Robot.build
+  end
+
+  test "robot has correct name" do
+    assert_equal "<%= file_name %>", @robot.name
+  end
+
+  test "robot has description" do
+    assert_not_nil @robot.description
+  end
+
+  test "robot has system prompt" do
+    assert_not_nil @robot.system_prompt
+  end
+end

data/lib/generators/robot_lab/templates/routing_robot.rb.tt

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# <%= class_name %> Routing Robot
+#
+# <%= robot_description %>
+#
+class <%= class_name %>Robot < 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: "<%= file_name %>",
+      description: "<%= robot_description %>",
+      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

data/lib/generators/robot_lab/templates/thread_model.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# RobotLab Thread Model
+#
+# Stores conversation threads for history persistence.
+#
+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/lib/robot_lab/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/robot_lab/rails.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "rails/version"
+require_relative "rails_integration/turbo_stream_callbacks"
+
+if defined?(::Rails)
+  require_relative "rails_integration/engine"
+  require_relative "rails_integration/railtie"
+  require_relative "rails_integration/job"
+end

data/lib/robot_lab/rails_integration/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module RailsIntegration
+    class Engine < ::Rails::Engine
+      isolate_namespace RobotLab
+
+      initializer "robot_lab.configure" do |app|
+        app.config.robot_lab ||= ActiveSupport::OrderedOptions.new
+      end
+
+      initializer "robot_lab.add_autoload_paths", before: :set_autoload_paths do |app|
+        app.config.autoload_paths << root.join("app", "robots")
+        app.config.autoload_paths << root.join("app", "tools")
+      end
+
+      config.generators do |g|
+        g.test_framework :minitest, fixture: false
+        g.fixture_replacement nil
+      end
+    end
+  end
+end

data/lib/robot_lab/rails_integration/job.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module RailsIntegration
+    # Base class for RobotLab background jobs.
+    #
+    # @example Minimal subclass using the robot_class DSL
+    #   class SupportRobotJob < RobotLab::Job
+    #     queue_as :default
+    #     robot_class SupportRobot
+    #   end
+    #
+    class Job < ActiveJob::Base
+      def self.robot_class(klass = nil)
+        klass ? @robot_class = klass : @robot_class
+      end
+
+      retry_on StandardError, wait: 5.seconds, attempts: 3
+      discard_on ActiveJob::DeserializationError
+
+      def perform(message:, robot_class: nil, thread_id: nil, **context)
+        klass  = resolve_robot_class(robot_class)
+        thread = setup_thread(thread_id, message)
+        robot  = build_robot(klass, thread_id)
+        result = robot.run(message, **context)
+
+        if thread
+          persist_result(thread, result)
+          broadcast_completion(thread_id)
+        end
+
+        result
+      rescue StandardError => e
+        broadcast_error(thread_id, e) if thread_id
+        raise
+      end
+
+      private
+
+      def resolve_robot_class(runtime_class)
+        klass = runtime_class || self.class.robot_class
+        raise ArgumentError,
+              "No robot class specified. Pass robot_class: to perform or set robot_class on the job class." \
+          unless klass
+
+        return klass if klass.is_a?(Class)
+
+        klass.to_s.constantize
+      end
+
+      def setup_thread(thread_id, message)
+        return nil unless thread_id
+
+        thread = "RobotLabThread".constantize.find_or_create_by_session_id(thread_id)
+        thread.update!(last_user_message: message, last_user_message_at: Time.current)
+        thread
+      end
+
+      def build_robot(klass, thread_id)
+        if thread_id && turbo_available?
+          stream_name  = "robot_lab_thread_#{thread_id}"
+          on_content   = TurboStreamCallbacks.build_content_callback(stream_name: stream_name)
+          on_tool_call = TurboStreamCallbacks.build_tool_call_callback(stream_name: stream_name)
+          klass.build(on_content: on_content, on_tool_call: on_tool_call)
+        else
+          klass.build
+        end
+      end
+
+      def persist_result(thread, result)
+        sequence = thread.results.maximum(:sequence_number).to_i + 1
+        exported = result.export
+
+        thread.results.create!(
+          robot_name:      result.robot_name,
+          sequence_number: sequence,
+          output_data:     exported[:output],
+          tool_calls_data: exported[:tool_calls],
+          stop_reason:     result.stop_reason,
+          checksum:        result.checksum
+        )
+      end
+
+      def broadcast_completion(thread_id)
+        return unless turbo_available?
+
+        Turbo::StreamsChannel.broadcast_replace_to(
+          "robot_lab_thread_#{thread_id}",
+          target: "robot_status",
+          html: "<div id=\"robot_status\"><span class=\"complete\">Complete</span></div>"
+        )
+      end
+
+      def broadcast_error(thread_id, error)
+        return unless turbo_available?
+
+        Turbo::StreamsChannel.broadcast_append_to(
+          "robot_lab_thread_#{thread_id}",
+          target: "robot_errors",
+          html: "<div class=\"error\">#{ERB::Util.html_escape(error.message)}</div>"
+        )
+      end
+
+      def turbo_available?
+        defined?(Turbo::StreamsChannel)
+      end
+    end
+  end
+end

data/lib/robot_lab/rails_integration/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module RailsIntegration
+    class Railtie < ::Rails::Railtie
+      config.robot_lab = ActiveSupport::OrderedOptions.new
+
+      initializer "robot_lab.configuration" do |app|
+        RobotLab.configure do |config|
+          rails_config = app.config.robot_lab
+
+          config.default_model    = rails_config.default_model    if rails_config.default_model
+          config.default_provider = rails_config.default_provider if rails_config.default_provider
+          config.logger           = ::Rails.logger
+        end
+      end
+
+      initializer "robot_lab.active_record" do
+        ActiveSupport.on_load(:active_record) do
+          # Extend ActiveRecord with RobotLab concerns if needed
+        end
+      end
+
+      rake_tasks do
+        path = File.expand_path("../tasks", __dir__)
+        Dir.glob("#{path}/**/*.rake").each { |f| load f }
+      end
+
+      generators do
+        require "generators/robot_lab/install_generator"
+        require "generators/robot_lab/robot_generator"
+        require "generators/robot_lab/job_generator"
+      end
+    end
+  end
+end

data/lib/robot_lab/rails_integration/turbo_stream_callbacks.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module RailsIntegration
+    # Stateless utility module that builds callback Procs for Turbo Stream broadcasting.
+    #
+    # Safe to require even without turbo-rails installed — checks at call time
+    # via `defined?(Turbo::StreamsChannel)`.
+    #
+    module TurboStreamCallbacks
+      def self.available?
+        defined?(Turbo::StreamsChannel) ? true : false
+      end
+
+      def self.build_content_callback(stream_name:, target: "robot_response")
+        ->(chunk) {
+          content = chunk.respond_to?(:content) ? chunk.content : chunk.to_s
+          return unless content && TurboStreamCallbacks.available?
+
+          Turbo::StreamsChannel.broadcast_append_to(
+            stream_name,
+            target: target,
+            html: ERB::Util.html_escape(content)
+          )
+        }
+      end
+
+      def self.build_tool_call_callback(stream_name:, target: "robot_tools")
+        ->(tool_call) {
+          return unless TurboStreamCallbacks.available?
+
+          name = tool_call.respond_to?(:name) ? tool_call.name : tool_call.to_s
+          Turbo::StreamsChannel.broadcast_append_to(
+            stream_name,
+            target: target,
+            html: "<span class=\"tool-badge\">Using: #{ERB::Util.html_escape(name)}</span>"
+          )
+        }
+      end
+    end
+  end
+end