robot_lab 0.0.12 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a8ae2e2cf690116950548d732987e16756870f8444c91504ea14fe039f25996
-  data.tar.gz: 115694d1449233b3a17a28e87deda8bd3d0ac204f51301aee7781156a3b2003e
+  metadata.gz: 9a1898a9909e7fdd795350b7f10cf80c57d69c1cec1b2533e56b9652cc2b3930
+  data.tar.gz: 641d4bd4022788a4ce53965a1ff8413ccf1420f71a1981f975618f825c29b80c
 SHA512:
-  metadata.gz: d512eea2ce533c92b4f791c0d3527fe61805fdca2638e926c0869e0e8f5b0c9a9dc5bac0791db2e5bae8a326b46eaea31c5ffae9ba761b17d1b93b3113735087
-  data.tar.gz: 7e6025d5bbe7252e61e4d7922eea639cda523d7c197535e46400caeeec7f30e7554a015cada107eef796a47c10564d286cdb1d2d4b539a7ac51cc71975b65352
+  metadata.gz: d51060ef5a929f5d9b895ba7e11220d47765fb92a342e9c3c76d5c223043747d53e7b924c9ecc53fccc90b90a0b08c180e75d5955527cc8b3cd99411a9c64026
+  data.tar.gz: c59f404518a69d97c65d960982367c582b8410d3754d3cf238ab8117f400eb229a02891bb449ab311bceaa16f0382c6cfd355c8f976bcc8f49b8191f8035e221

data/CHANGELOG.md

@@ -8,6 +8,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-04-29
+
+### Added
+
+- **`RobotLab::Job` base class** (`lib/robot_lab/rails_integration/job.rb`) — `ActiveJob::Base` subclass encapsulating the full robot-run lifecycle for Rails background jobs
+  - `robot_class` DSL — bind a job subclass to a specific robot class at the class level; per-subclass, not inherited
+  - `perform(message:, robot_class: nil, thread_id: nil, **context)` — resolves robot class, wires Turbo Stream callbacks, runs robot, persists `RobotResult`, broadcasts completion/error
+  - `thread_id` omitted → fire-and-forget mode (no persistence, no broadcasting)
+  - Turbo Stream wiring is a graceful no-op when `turbo-rails` is absent
+  - `retry_on StandardError, wait: 5.seconds, attempts: 3` and `discard_on ActiveJob::DeserializationError` configured by default
+  - `RobotLab::Job` top-level alias registered in `robot_lab.rb` when Rails is present so job subclasses can write `< RobotLab::Job`
+- **`rails generate robot_lab:job NAME`** (`lib/generators/robot_lab/job_generator.rb`) — generates a dedicated job subclass pre-wired to `<NAME>Robot` via `robot_class` DSL
+  - `--queue` option (default `"default"`)
+  - Template: `lib/generators/robot_lab/templates/robot_job.rb.tt`
+- **`max_concurrent_robots` field on `RunConfig`** — caps the number of fiber-concurrent robots in a parallel network execution; passed to `SimpleFlow::Pipeline#call_parallel` as `max_concurrent:`
+- **Example 31: Launch Assessment** (`examples/31_launch_assessment.rb`) — six `AnalystRobot` instances run in parallel (market, competitive, tech, risk, financial, legal) with a cap of 4 concurrent robots; a `LaunchDirector` synthesizes findings into a GO/NO-GO decision
+- **20 unit tests for `RobotLab::RailsIntegration::Job`** (`test/robot_lab/rails_integration/job_test.rb`) covering `robot_class` DSL, `resolve_robot_class`, `setup_thread`, `build_robot`, `broadcast_completion`, `broadcast_error`, and `turbo_available?`
+
+### Changed
+
+- Bumped version to 0.1.0
+- **`RobotRunJob` (generated job)** is now a thin two-line subclass of `RobotLab::Job` — all lifecycle logic lives in the base class
+- **`job.rb.tt` install generator template** updated to the thin-subclass pattern
+- **`examples/18_rails` `RobotRunJob`** updated to thin subclass
+- **`Network#call_parallel`** now forwards `max_concurrent: @config.max_concurrent_robots` to `SimpleFlow::Pipeline`, enabling the concurrency cap introduced in `RunConfig`
+
+### Fixed
+
+- **`Message.from_hash`** — records persisted without a `type` key (e.g. legacy user-message rows) previously raised `ArgumentError: missing keyword: :type`; `from_hash` now defaults a nil or absent `type` to `"text"` so old rows deserialize as `TextMessage` without error
+
+### Documentation
+
+- **`docs/guides/rails-integration.md`** — rewrote Background Jobs section to document `RobotLab::Job` base class, lifecycle steps, `robot_class` DSL, dedicated job generator, fire-and-forget mode, and when to use a custom `ApplicationJob` instead
+- **`docs/api/messages/index.md`** — added "Deserializing from Hash" section documenting `Message.from_hash` dispatch logic and the missing-type fallback
+- **README.md** — expanded Rails Integration section with full Background Jobs documentation including both generic and dedicated job patterns
+
 ## [0.0.12] - 2026-04-18
 
 ### Added

data/README.md

@@ -842,6 +842,56 @@ This creates:
 - `app/robots/` - Directory for your robots
 - Database tables for conversation history
 
+### Background Jobs
+
+RobotLab ships with `RobotLab::Job`, an `ActiveJob::Base` subclass that handles the full robot-run lifecycle: robot class resolution, Turbo Stream wiring, thread-record persistence, and completion/error broadcasting.
+
+**Generic job** (robot class supplied at enqueue time):
+
+```bash
+rails generate robot_lab:install   # creates app/jobs/robot_run_job.rb
+```
+
+```ruby
+# app/jobs/robot_run_job.rb  (generated)
+class RobotRunJob < RobotLab::Job
+  queue_as :default
+end
+
+# Enqueue from a controller:
+RobotRunJob.perform_later(
+  robot_class: "SupportRobot",
+  message:     params[:message],
+  thread_id:   session_id
+)
+```
+
+**Dedicated job** (robot class bound at the class level via DSL):
+
+```bash
+rails generate robot_lab:job Support            # binds to SupportRobot, queue: default
+rails generate robot_lab:job Support --queue ai # custom queue
+```
+
+```ruby
+# app/jobs/support_job.rb  (generated)
+class SupportJob < RobotLab::Job
+  queue_as :default
+  robot_class SupportRobot
+end
+
+# Enqueue (no robot_class: needed):
+SupportJob.perform_later(message: params[:message], thread_id: session_id)
+```
+
+When `thread_id` is provided and [turbo-rails](https://github.com/hotwired/turbo-rails) is installed, `RobotLab::Job` automatically:
+
+- Wires `on_content` / `on_tool_call` Turbo Stream callbacks so the UI updates in real time
+- Broadcasts a **completion** event to `"robot_lab_thread_#{thread_id}"` when the run finishes
+- Broadcasts an **error** event (HTML-escaped) if the job raises
+
+Omitting `thread_id` runs the robot in fire-and-forget mode — no persistence, no broadcasting.
+
 ## Documentation
 
 Full documentation is available at **[https://madbomber.github.io/robot_lab](https://madbomber.github.io/robot_lab)**

data/docs/api/messages/index.md

@@ -76,6 +76,27 @@ memory.messages  # => Array<Message>
 memory.format_history  # => Array<Message>
 ```
 
+## Deserializing from Hash
+
+`Message.from_hash` reconstructs the correct subclass from a stored hash:
+
+```ruby
+RobotLab::Message.from_hash({ type: "text", role: "user", content: "Hello" })
+# => #<RobotLab::TextMessage ...>
+
+RobotLab::Message.from_hash({ type: "tool_call", role: "assistant", tools: [...] })
+# => #<RobotLab::ToolCallMessage ...>
+```
+
+When the `type` key is absent or `nil` (e.g. records persisted before the field was introduced), `from_hash` defaults to `TextMessage`:
+
+```ruby
+RobotLab::Message.from_hash({ role: "user", content: "legacy row" })
+# => #<RobotLab::TextMessage ...>
+```
+
+String keys are normalised automatically via `transform_keys(&:to_sym)`.
+
 ## See Also
 
 - [Memory](../core/memory.md)

data/docs/getting-started/configuration.md

@@ -361,7 +361,7 @@ effective.temperature  #=> 0.9 (overridden)
 | **LLM** | `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` |
 | **Tools** | `mcp`, `tools` |
 | **Callbacks** | `on_tool_call`, `on_tool_result` |
-| **Infrastructure** | `bus`, `enable_cache` |
+| **Infrastructure** | `bus`, `enable_cache`, `max_tool_rounds`, `token_budget`, `ractor_pool_size`, `max_concurrent_robots` |
 
 ### RunConfig vs RobotLab.config
 

data/docs/guides/creating-networks.md

@@ -84,6 +84,29 @@ network = RobotLab.create_network(name: "parallel_analysis") do
 end
 ```
 
+### Concurrency Cap
+
+When a network fans out to many parallel robots, each makes a simultaneous LLM API call. With no limit this can exhaust API rate-limit quotas or database connection pools under load. Set `max_concurrent_robots:` on a `RunConfig` to cap how many robot tasks run at once — the rest queue behind an `Async::Semaphore` and start as slots open:
+
+```ruby
+config = RobotLab::RunConfig.new(max_concurrent_robots: 4)
+
+network = RobotLab.create_network(name: "launch_assessment", config: config) do
+  # All six declared parallel, but at most 4 LLM calls in-flight simultaneously
+  task :market,     market_robot,     depends_on: :none
+  task :competitive, comp_robot,      depends_on: :none
+  task :tech,       tech_robot,       depends_on: :none
+  task :risk,       risk_robot,       depends_on: :none
+  task :financial,  financial_robot,  depends_on: :none  # queues until a slot opens
+  task :legal,      legal_robot,      depends_on: :none  # queues until a slot opens
+
+  task :director, director_robot, depends_on: [:market, :competitive, :tech,
+                                               :risk, :financial, :legal]
+end
+```
+
+`nil` (the default) means unlimited — identical to pre-existing behavior. For Rails deployments, size the cap to match your database connection pool and API rate tier. See [Example 31](../../examples/31_launch_assessment.rb) for a working demo.
+
 ### Optional Tasks
 
 Optional tasks only run when explicitly activated by a preceding robot:

data/docs/guides/rails-integration.md

@@ -362,34 +362,73 @@ 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 `app/jobs/robot_run_job.rb` — an ActiveJob class that wraps robot execution with result persistence and optional Turbo Stream broadcasting.
+The install generator creates a thin subclass you can enqueue with any robot class at runtime:
+
+```ruby title="app/jobs/robot_run_job.rb"
+class RobotRunJob < RobotLab::Job
+  queue_as :default
+end
+```
 
 ```ruby
-# Enqueue from a controller
+# Enqueue from a controller — pass robot_class: as a string
 RobotRunJob.perform_later(
   robot_class: "SupportRobot",
-  message: params[:message],
-  thread_id: session_id
+  message:     params[:message],
+  thread_id:   session_id
 )
 
 render json: { status: "processing" }
 ```
 
-The job:
+### Dedicated Job (robot_class DSL)
 
-1. Finds or creates a `RobotLabThread` by `thread_id`
-2. Resolves the robot class via `constantize.build`
-3. Wires Turbo Stream callbacks when `turbo-rails` is available (graceful no-op otherwise)
-4. Runs the robot and persists the result to `RobotLabResult`
-5. Broadcasts completion or error events via Turbo Streams
+Generate a job pre-bound to a specific robot class so callers never need to pass `robot_class:`:
+
+```bash
+rails generate robot_lab:job Support            # binds to SupportRobot, queue: default
+rails generate robot_lab:job Support --queue ai # custom queue name
+```
 
-Customize the generated job to change queue name, retry policy, or error handling.
+```ruby title="app/jobs/support_job.rb"
+class SupportJob < RobotLab::Job
+  queue_as :default
+  robot_class SupportRobot
+end
+```
+
+```ruby
+# 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:
+
+```ruby
+RobotRunJob.perform_later(robot_class: "ChatRobot", message: "ping")
+```
 
 ### Turbo Stream Token Streaming
 
-When `turbo-rails` is installed, `RobotRunJob` automatically streams content tokens and tool call badges to the browser in real time.
+When `turbo-rails` is installed, `RobotLab::Job` automatically streams content tokens and tool call badges to the browser in real time.
 
 #### View Setup
 
@@ -435,7 +474,7 @@ The stream name convention is `"robot_lab_thread_#{thread_id}"`, matching the `R
 
 ### Custom Background Job
 
-For full control, write your own job instead of using the generated one:
+For full control outside of the `RobotLab::Job` lifecycle (e.g. custom persistence or a different broadcasting strategy), inherit from `ApplicationJob` directly:
 
 ```ruby title="app/jobs/process_message_job.rb"
 class ProcessMessageJob < ApplicationJob

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

@@ -1,79 +1,19 @@
 # frozen_string_literal: true
 
-class RobotRunJob < ApplicationJob
+# 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
-
-  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: "<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

data/examples/31_launch_assessment.rb

@@ -0,0 +1,248 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 31: Product Launch Assessment — 6 Parallel Analysts, Cap of 4
+#
+# Six specialist robots evaluate a product launch simultaneously.
+# max_concurrent_robots: 4 ensures at most 4 LLM API calls are in-flight
+# at once. Robots 5 and 6 queue behind the Async::Semaphore and start as
+# soon as any of the first 4 finishes — providing natural back-pressure
+# without slowing the pipeline more than necessary.
+#
+# Architecture:
+#
+#   ┌──────────────────────────────────────────────────────────────────────┐
+#   │          PARALLEL ANALYSIS PHASE  (max_concurrent_robots: 4)        │
+#   │                                                                      │
+#   │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
+#   │  │  Market  │  │  Compet. │  │   Tech   │  │   Risk   │  slots 1-4 │
+#   │  │ Analyst  │  │ Analyst  │  │ Reviewer │  │ Assessor │            │
+#   │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘            │
+#   │       │             │             │             │                    │
+#   │    start          start         start         start                 │
+#   │                                                                      │
+#   │  ┌──────────┐  ┌──────────┐                                         │
+#   │  │Financial │  │  Legal   │  queued — start when a slot opens       │
+#   │  │ Reviewer │  │ Reviewer │                                         │
+#   │  └────┬─────┘  └────┬─────┘                                         │
+#   │       │             │                                                │
+#   │    (deferred)    (deferred)                                          │
+#   │                                                                      │
+#   │  ┌─────────────────────────────────────────────────────────────┐    │
+#   │  │                  SHARED MEMORY                               │    │
+#   │  │  :market  :competitive  :tech  :risk  :financial  :legal     │    │
+#   │  └─────────────────────────────────────────────────────────────┘    │
+#   │                              │                                       │
+#   │                              ▼                                       │
+#   │  ┌─────────────────────────────────────────────────────────────┐    │
+#   │  │                 Launch Director                               │    │
+#   │  │   Blocks on reactive memory until all 6 findings arrive,     │    │
+#   │  │   then issues a GO / NO-GO recommendation.                   │    │
+#   │  └─────────────────────────────────────────────────────────────┘    │
+#   └──────────────────────────────────────────────────────────────────────┘
+#
+# Key config:
+#   RunConfig.new(max_concurrent_robots: 4)
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/31_launch_assessment.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+RubyLLM.configure { |c| c.logger = Logger.new(File::NULL) }
+
+# ── AnalystRobot ────────────────────────────────────────────────────────────────
+#
+# Runs its LLM call, writes the verdict to shared memory, and logs a timing line
+# so you can see when the semaphore releases robots 5 and 6.
+
+class AnalystRobot < RobotLab::Robot
+  attr_reader :memory_key
+  attr_writer :shared_memory
+
+  def initialize(name:, memory_key:, role:)
+    super(
+      name:          name,
+      system_prompt: "You are a #{role}. " \
+                     "Review the product brief in 2-3 crisp sentences from your area of expertise. " \
+                     "Close with a one-word verdict: READY or NOT-READY."
+    )
+    @memory_key = memory_key
+  end
+
+  def call(result)
+    brief   = extract_brief(result)
+    started = Time.now
+    puts "  [#{name}] started at +#{"%.1f" % (started - $run_start)}s"
+
+    verdict = run(brief).reply.strip
+
+    elapsed = "%.1f" % (Time.now - started)
+    puts "  [#{name}] finished in #{elapsed}s — #{verdict.split.last(2).join(" ")}"
+
+    if @shared_memory
+      @shared_memory.current_writer = name
+      @shared_memory.set(@memory_key, verdict)
+    end
+
+    result.with_context(name.to_sym, verdict).continue(verdict)
+  end
+
+  private
+
+  def extract_brief(result)
+    case result.value
+    when Hash                  then result.value[:message].to_s
+    when RobotLab::RobotResult then result.value.reply.to_s
+    else                            result.value.to_s
+    end
+  end
+end
+
+# ── LaunchDirector ──────────────────────────────────────────────────────────────
+#
+# Waits for all 6 findings via reactive memory, then issues the final call.
+# SimpleFlow guarantees the six analyst tasks are done before this task runs,
+# so the memory.get is effectively a non-blocking read by the time we arrive here.
+
+class LaunchDirector < RobotLab::Robot
+  attr_writer :shared_memory
+
+  FINDING_KEYS = %i[market competitive tech risk financial legal].freeze
+
+  def call(result)
+    puts "  [#{name}] reading all findings from shared memory..."
+    findings = @shared_memory.get(*FINDING_KEYS, wait: 120)
+
+    if findings.values.any? { |v| v == :timeout }
+      timed_out = findings.select { |_, v| v == :timeout }.keys
+      puts "  [#{name}] WARNING: timed out waiting for: #{timed_out.join(", ")}"
+    end
+
+    prompt = <<~PROMPT
+      Six specialist analysts have reviewed our product launch readiness.
+      Based on their findings, issue a final GO or NO-GO recommendation
+      in 3-5 sentences. Be direct and specific about the key deciding factors.
+
+      Market analysis:      #{findings[:market]      || "(not received)"}
+      Competitive analysis: #{findings[:competitive] || "(not received)"}
+      Technical review:     #{findings[:tech]        || "(not received)"}
+      Risk assessment:      #{findings[:risk]        || "(not received)"}
+      Financial review:     #{findings[:financial]   || "(not received)"}
+      Legal review:         #{findings[:legal]       || "(not received)"}
+
+      Begin your response with "GO -" or "NO-GO -".
+    PROMPT
+
+    recommendation = run(prompt).reply.strip
+    @shared_memory.set(:recommendation, recommendation)
+    puts "  [#{name}] recommendation ready"
+
+    result.with_context(:recommendation, recommendation).continue(recommendation)
+  end
+end
+
+# ── Product Brief ───────────────────────────────────────────────────────────────
+
+PRODUCT_BRIEF = <<~BRIEF
+  Product: "Orion" — an AI-powered project management tool that auto-generates
+  sprint plans from Jira backlogs, detects scope creep in real-time, and integrates
+  with GitHub and Slack via webhooks. SaaS pricing: $25/seat/month, 14-day free trial.
+  Target: mid-size engineering teams (20-200 developers). Launch date: 6 weeks out.
+  Beta: 12 paying customers, 94% satisfaction, 0 critical bugs open. SOC 2 Type I
+  certification in progress, expected within 30 days.
+BRIEF
+
+# ── Build the six analysts ───────────────────────────────────────────────────────
+
+ANALYSTS = [
+  { name: "market_analyst",      key: :market,      role: "market opportunity analyst"             },
+  { name: "competitive_analyst", key: :competitive, role: "competitive intelligence analyst"       },
+  { name: "tech_reviewer",       key: :tech,        role: "technical readiness and quality reviewer" },
+  { name: "risk_assessor",       key: :risk,        role: "product risk assessment specialist"    },
+  { name: "financial_reviewer",  key: :financial,   role: "financial viability and pricing analyst" },
+  { name: "legal_reviewer",      key: :legal,       role: "legal, compliance, and IP reviewer"    },
+].freeze
+
+analyst_robots = ANALYSTS.map do |spec|
+  AnalystRobot.new(name: spec[:name], memory_key: spec[:key], role: spec[:role])
+end
+
+director = LaunchDirector.new(
+  name:          "launch_director",
+  system_prompt: "You are the VP of Product making the final launch call."
+)
+
+# ── Network — note the concurrency cap ──────────────────────────────────────────
+
+config = RobotLab::RunConfig.new(max_concurrent_robots: 4)
+
+analyst_names = analyst_robots.map { |r| r.name.to_sym }
+
+network = RobotLab.create_network(name: "launch_assessment", config: config) do
+  analyst_robots.each do |robot|
+    task robot.name.to_sym, robot, depends_on: :none
+  end
+
+  task :launch_director, director, depends_on: analyst_names
+end
+
+# Assign shared memory so each robot can write to it directly
+shared_memory = network.memory
+(analyst_robots + [director]).each { |r| r.shared_memory = shared_memory }
+
+# Subscribe for a memory-level audit trail
+analyst_robots.each do |robot|
+  network.memory.subscribe(robot.memory_key) do |change|
+    puts "  [memory] :#{change.key} written by #{change.writer}"
+  end
+end
+
+# ── Run ─────────────────────────────────────────────────────────────────────────
+
+puts "=" * 68
+puts "Example 31: Product Launch Assessment"
+puts "  6 specialist analysts in parallel, max_concurrent_robots: 4"
+puts "=" * 68
+puts
+puts "Pipeline:"
+puts network.visualize
+puts
+puts "Concurrency config: #{config.inspect}"
+puts
+puts "Product brief:"
+puts PRODUCT_BRIEF.strip.gsub(/^/, "  ")
+puts
+puts "-" * 68
+puts "Running — analysts 5 and 6 queue until a semaphore slot opens..."
+puts "-" * 68
+puts
+
+$run_start = Time.now
+result     = network.run(message: PRODUCT_BRIEF)
+elapsed    = "%.1f" % (Time.now - $run_start)
+
+puts
+puts "-" * 68
+puts "All analysts complete. Total wall time: #{elapsed}s"
+puts "-" * 68
+puts
+puts "=" * 68
+puts "LAUNCH DIRECTOR RECOMMENDATION"
+puts "=" * 68
+puts
+puts network.memory[:recommendation]
+puts
+puts "=" * 68
+puts "INDIVIDUAL ANALYST VERDICTS"
+puts "=" * 68
+puts
+analyst_robots.each do |robot|
+  label  = robot.name.gsub("_", " ").upcase
+  finding = network.memory.get(robot.memory_key).to_s
+  puts "#{label}"
+  puts finding
+  puts
+end

data/examples/README.md

@@ -57,6 +57,7 @@ examples/
   26_document_store.rb        # Embedding-based document store (RAG) via fastembed
   29_ractor_tools.rb          # Ractor-safe tools: worker pool, freeze_deep, parallel batch
   30_ractor_network.rb        # Ractor network scheduler: dependency waves, parallel_mode
+  31_launch_assessment.rb     # 6 parallel analysts, max_concurrent_robots: 4 semaphore cap
   18_rails/                   # Minimal Rails 8 demo app (full integration)
     app/robots/chat_robot.rb  #   Robot factory with system prompt + TimeTool
     app/tools/time_tool.rb    #   Custom RobotLab::Tool subclass
@@ -297,6 +298,14 @@ and the `pipeline.step_dependencies` dependency graph inspection.
 
 **Requires:** None for Parts 1 & 2.  LLM API key for Part 3.
 
+### 31 — Product Launch Assessment (Concurrency Cap)
+
+Six specialist robots evaluate a product launch simultaneously: market, competitive, technical, risk, financial, and legal analysts. `RunConfig.new(max_concurrent_robots: 4)` caps the `Async::Semaphore` at 4 in-flight LLM calls — robots 5 and 6 queue until a slot opens. A `LaunchDirector` reads all six findings from shared reactive memory and issues a GO / NO-GO recommendation. Start timestamps in the output make the semaphore behavior visible.
+
+Demonstrates: `max_concurrent_robots:` on `RunConfig`, `Async::Semaphore` back-pressure via `simple_flow`, six parallel `depends_on: :none` tasks, shared memory writes and blocking reads.
+
+**Requires:** LLM API key
+
 ### 18 — Rails Integration Demo
 
 A minimal, hand-built Rails 8 app that exercises every piece of RobotLab's Rails integration end-to-end. No `rails new` — every file is hand-crafted for minimum size.

data/lib/generators/robot_lab/job_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RobotLab
+  module Generators
+    # Generates a RobotLab job subclass pre-wired to a specific robot class.
+    #
+    # Usage:
+    #   rails generate robot_lab:job NAME [options]
+    #
+    # Examples:
+    #   rails generate robot_lab:job Support
+    #   # => app/jobs/support_job.rb  (robot_class SupportRobot)
+    #
+    class JobGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :queue, type: :string, default: "default",
+                           desc: "ActiveJob queue name"
+
+      # Creates the job file.
+      #
+      # @return [void]
+      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/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.12"
+  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.12
+  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
@@ -396,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
@@ -446,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
@@ -484,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