robot_lab 0.0.11 → 0.1.0

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

@@ -1,92 +1,21 @@
 # frozen_string_literal: true
 
-# Background job for executing robot runs asynchronously.
+# Generic background job for executing any robot asynchronously.
 #
-# Resolves a robot class, optionally wires Turbo Stream callbacks for
-# real-time token streaming, persists the result, and broadcasts
-# completion/error events.
+# 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
+#     message:     params[:message],
+#     thread_id:   session_id
 #   )
 #
-class RobotRunJob < ApplicationJob
+class RobotRunJob < RobotLab::Job
   queue_as :default
-
-  retry_on StandardError, wait: 5.seconds, attempts: 3
-  discard_on ActiveJob::DeserializationError
-
-  def perform(robot_class:, message:, thread_id:, **context)
-    thread = RobotLabThread.find_or_create_by_session_id(thread_id)
-    thread.update!(last_user_message: message, last_user_message_at: Time.current)
-
-    robot  = resolve_robot(robot_class, thread_id)
-    result = robot.run(message, **context)
-
-    persist_result(thread, result)
-    broadcast_completion(thread_id)
-  rescue StandardError => e
-    broadcast_error(thread_id, e)
-    raise
-  end
-
-  private
-
-  def resolve_robot(robot_class, thread_id)
-    klass       = robot_class.to_s.constantize
-    stream_name = "robot_lab_thread_#{thread_id}"
-
-    if turbo_available?
-      on_content = RobotLab::RailsIntegration::TurboStreamCallbacks.build_content_callback(
-        stream_name: stream_name
-      )
-      on_tool_call = RobotLab::RailsIntegration::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: "<span class=\"robot-status-complete\">Complete</span>"
-    )
-  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=\"robot-error\">#{ERB::Util.html_escape(error.message)}</div>"
-    )
-  end
-
-  def turbo_available?
-    defined?(Turbo::StreamsChannel)
-  end
 end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Background job that runs <%= robot_class_name %> asynchronously.
+#
+# Inherits from RobotLab::Job — Turbo Stream wiring, thread persistence,
+# and completion/error broadcasting are all handled by the base class.
+#
+# @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/robot_lab/message.rb

@@ -92,7 +92,7 @@ module RobotLab
     def self.from_hash(hash)
       hash = hash.transform_keys(&:to_sym)
 
-      case hash[:type]&.to_s
+      case (hash[:type] || "text").to_s
       when "text"
         TextMessage.new(**hash.slice(:role, :content, :stop_reason))
       when "tool_call"

data/lib/robot_lab/network.rb

@@ -190,7 +190,7 @@ module RobotLab
           run_context,
           context: { run_params: run_context }
         )
-        @pipeline.call_parallel(initial_result)
+        @pipeline.call_parallel(initial_result, max_concurrent: @config.max_concurrent_robots)
       end
     end
 

data/lib/robot_lab/rails_integration/job.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module RailsIntegration
+    # Base class for RobotLab background jobs.
+    #
+    # Encapsulates the full robot-run lifecycle: robot class resolution,
+    # Turbo Stream callback wiring, thread-record persistence, and
+    # completion/error broadcasting. Suitable for fiber-safe execution
+    # under Solid Queue's fiber mode (see issue #20 for SQ version details).
+    #
+    # @example Minimal subclass using the robot_class DSL
+    #   class SupportRobotJob < RobotLab::Job
+    #     queue_as :default
+    #     robot_class SupportRobot
+    #   end
+    #
+    #   # Enqueue (no robot_class: needed — taken from DSL):
+    #   SupportRobotJob.perform_later(message: "Hello", thread_id: session_id)
+    #
+    # @example Generic job accepting robot_class at enqueue time
+    #   class RobotRunJob < RobotLab::Job
+    #     queue_as :default
+    #   end
+    #
+    #   RobotRunJob.perform_later(
+    #     robot_class: "SupportRobot",
+    #     message:     params[:message],
+    #     thread_id:   session_id
+    #   )
+    #
+    class Job < ActiveJob::Base
+      # Set or get the default robot class for this job subclass.
+      #
+      # @overload robot_class
+      #   @return [Class, nil] the configured robot class
+      # @overload robot_class(klass)
+      #   @param klass [Class] the robot class (must respond to .build)
+      #   @return [Class]
+      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
+
+      # Run a robot as a background job.
+      #
+      # When +thread_id+ is provided the job:
+      # - Finds or creates a +RobotLabThread+ record and updates its last-message fields
+      # - Wires +TurboStreamCallbacks+ onto the robot (when turbo-rails is present)
+      # - Persists the +RobotResult+ to +RobotLabResult+
+      # - Broadcasts a completion or error event via Turbo Streams
+      #
+      # When +thread_id+ is omitted the robot runs in a fire-and-forget mode —
+      # no persistence, no broadcasting, result returned directly.
+      #
+      # @param message [String] the user message forwarded to robot.run
+      # @param robot_class [String, Class, nil] override; falls back to the class-level DSL
+      # @param thread_id [String, nil] session key for persistence and Turbo broadcasting
+      # @param context [Hash] additional keyword args forwarded to robot.run
+      # @return [RobotResult]
+      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
+
+      # Resolve the robot class from the runtime arg or the class-level DSL.
+      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
+
+      # Find or create the thread record and stamp the incoming message.
+      # Returns nil when thread_id is absent (fire-and-forget mode).
+      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
+
+      # Build the robot, wiring Turbo callbacks when thread_id + turbo-rails are present.
+      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
+
+      # Append a RobotLabResult record to the thread.
+      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
+
+      # Broadcast a "Complete" badge to the Turbo Stream.
+      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
+
+      # Broadcast an HTML-escaped error message to the Turbo Stream.
+      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

@@ -33,9 +33,18 @@ module RobotLab
         Dir.glob("#{path}/**/*.rake").each { |f| load f }
       end
 
+      # TODO: Add fiber isolation warning once Solid Queue fiber mode lands in a
+      # mainline release. PR rails/solid_queue#728 (branch crmne/solid_queue
+      # async-worker-execution-mode) introduces the `fibers:` worker key but has
+      # not yet been merged or released. When a released version is detectable,
+      # add an initializer here that warns when:
+      #   defined?(SolidQueue) &&
+      #   app.config.active_support.isolation_level != :fiber
+
       generators do
         require "generators/robot_lab/install_generator"
         require "generators/robot_lab/robot_generator"
+        require "generators/robot_lab/job_generator"
       end
     end
   end

data/lib/robot_lab/run_config.rb

@@ -41,7 +41,7 @@ module RobotLab
     CALLBACK_FIELDS = %i[on_tool_call on_tool_result on_content].freeze
 
     # Infrastructure fields
-    INFRA_FIELDS = %i[bus enable_cache max_tool_rounds token_budget ractor_pool_size].freeze
+    INFRA_FIELDS = %i[bus enable_cache max_tool_rounds token_budget ractor_pool_size max_concurrent_robots].freeze
 
     # All recognized fields
     FIELDS = (LLM_FIELDS + TOOL_FIELDS + CALLBACK_FIELDS + INFRA_FIELDS).freeze

data/lib/robot_lab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RobotLab
-  VERSION = "0.0.11"
+  VERSION = "0.1.0"
 end

data/lib/robot_lab.rb

@@ -251,4 +251,8 @@ if defined?(Rails::Engine)
   require 'robot_lab/rails_integration/engine'
   require 'robot_lab/rails_integration/railtie'
   require 'robot_lab/rails_integration/turbo_stream_callbacks'
+  require 'robot_lab/rails_integration/job'
+
+  # Convenience alias so job subclasses can inherit from RobotLab::Job
+  RobotLab::Job = RobotLab::RailsIntegration::Job
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.1.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -155,14 +155,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: ractor_queue
   requirement: !ruby/object:Gem::Requirement
@@ -234,7 +234,6 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
-- ".github/workflows/deploy-yard-docs.yml"
 - ".irbrc"
 - CHANGELOG.md
 - COMMITS.md
@@ -244,9 +243,11 @@ files:
 - docs/api/core/index.md
 - docs/api/core/memory.md
 - docs/api/core/network.md
+- docs/api/core/result.md
 - docs/api/core/robot.md
 - docs/api/core/state.md
 - docs/api/core/tool.md
+- docs/api/errors.md
 - docs/api/index.md
 - docs/api/mcp/client.md
 - docs/api/mcp/index.md
@@ -394,6 +395,7 @@ files:
 - examples/28_mcp_discovery.rb
 - examples/29_ractor_tools.rb
 - examples/30_ractor_network.rb
+- examples/31_launch_assessment.rb
 - examples/README.md
 - examples/prompts/assistant.md
 - examples/prompts/audit_trail.md
@@ -444,12 +446,14 @@ files:
 - examples/prompts/template_with_skills_test.md
 - examples/prompts/triage.md
 - lib/generators/robot_lab/install_generator.rb
+- lib/generators/robot_lab/job_generator.rb
 - lib/generators/robot_lab/robot_generator.rb
 - lib/generators/robot_lab/templates/initializer.rb.tt
 - lib/generators/robot_lab/templates/job.rb.tt
 - lib/generators/robot_lab/templates/migration.rb.tt
 - lib/generators/robot_lab/templates/result_model.rb.tt
 - lib/generators/robot_lab/templates/robot.rb.tt
+- lib/generators/robot_lab/templates/robot_job.rb.tt
 - lib/generators/robot_lab/templates/robot_test.rb.tt
 - lib/generators/robot_lab/templates/routing_robot.rb.tt
 - lib/generators/robot_lab/templates/thread_model.rb.tt
@@ -482,6 +486,7 @@ files:
 - lib/robot_lab/ractor_network_scheduler.rb
 - lib/robot_lab/ractor_worker_pool.rb
 - lib/robot_lab/rails_integration/engine.rb
+- lib/robot_lab/rails_integration/job.rb
 - lib/robot_lab/rails_integration/railtie.rb
 - lib/robot_lab/rails_integration/turbo_stream_callbacks.rb
 - lib/robot_lab/robot.rb

data/.github/workflows/deploy-yard-docs.yml

@@ -1,52 +0,0 @@
-name: Deploy YARD Documentation to GitHub Pages
-on:
-  push:
-    branches:
-      - main
-      - develop
-    paths:
-      - "lib/**"
-      - "docs/assets/**"
-      - ".yardopts"
-      - "*.gemspec"
-      - ".github/workflows/deploy-yard-docs.yml"
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  pages: write
-  id-token: write
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.3"
-          bundler-cache: true
-
-      - name: Install YARD
-        run: gem install yard
-
-      - name: Build YARD documentation
-        run: yard doc
-
-      - name: Configure Git
-        run: |
-          git config --local user.email "action@github.com"
-          git config --local user.name "GitHub Action"
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./doc
-          destination_dir: yard
-          keep_files: true