robot_lab 0.0.11 → 0.1.0

data/docs/guides/building-robots.md

@@ -736,6 +736,131 @@ bot = RobotLab.build(name: "latecomer", system_prompt: "Hello.")
 bot.with_bus(existing_bus)  # now connected and can send/receive messages
 ```
 
+## Context Window Compression
+
+Long-running robots accumulate conversation history that can grow to fill the context window. `compress_history` prunes old turns using TF-IDF cosine similarity against the most recent context, keeping turns that are still relevant and discarding or summarizing those that aren't.
+
+```ruby
+# Default settings: protect 3 most-recent turn pairs, drop anything below 0.2
+robot.compress_history
+
+# Tune all thresholds
+robot.compress_history(
+  recent_turns:   5,    # number of recent user+assistant pairs to always keep
+  keep_threshold: 0.6,  # turns with score >= this are kept verbatim (default 0.6)
+  drop_threshold: 0.2   # turns with score < this are dropped (default 0.2)
+)
+```
+
+Medium-relevance turns (between thresholds) are dropped by default. Pass a `summarizer:` callable to replace them with a one-sentence summary instead:
+
+```ruby
+summarizer = RobotLab.build(name: "summarizer", system_prompt: "Summarize concisely in one sentence.")
+
+robot.compress_history(
+  summarizer: ->(text) { summarizer.run("Summarize: #{text}").reply }
+)
+```
+
+**What is always preserved regardless of score:**
+- System messages
+- Tool call/result message pairs (dropping half would corrupt the conversation)
+- The most recent `recent_turns` user+assistant pairs
+
+Requires the `classifier` gem (`~> 2.3`):
+
+```ruby
+gem "classifier", "~> 2.3"
+```
+
+## Convergence Detection
+
+`RobotLab::Convergence` uses TF-IDF cosine similarity to detect when two independent agents have reached the same conclusion. The primary use case is a network router that skips an expensive reconciler robot when two verifiers already agree.
+
+```ruby
+# Check the similarity score directly (returns Float 0.0..1.0)
+score = RobotLab::Convergence.similarity(result_a.reply, result_b.reply)
+
+# Boolean convergence check (default threshold: 0.85)
+RobotLab::Convergence.detected?(result_a.reply, result_b.reply)
+
+# Custom threshold
+RobotLab::Convergence.detected?(text_a, text_b, threshold: 0.75)
+```
+
+Wire it into a network router for the reconciler fast-path:
+
+```ruby
+verifier_a = RobotLab.build(name: "verifier_a", system_prompt: "Verify the answer.")
+verifier_b = RobotLab.build(name: "verifier_b", system_prompt: "Independently verify the answer.")
+reconciler = RobotLab.build(name: "reconciler", system_prompt: "Reconcile conflicting answers.")
+
+router = lambda do |args|
+  a = args.context[:verifier_a]&.reply.to_s
+  b = args.context[:verifier_b]&.reply.to_s
+
+  # Skip reconciler when verifiers agree
+  RobotLab::Convergence.detected?(a, b) ? nil : ["reconciler"]
+end
+
+network = RobotLab.create_network(name: "verify", router: router) do
+  # ...
+end
+```
+
+Requires the `classifier` gem (`~> 2.3`).
+
+## Structured Delegation
+
+A robot can delegate a task to another robot using `delegate(to:, task:)`. The result is a `RobotResult` annotated with `delegated_by`, `duration`, and token counts.
+
+### Synchronous Delegation
+
+The default: blocks the calling robot until the delegatee finishes.
+
+```ruby
+analyst = RobotLab.build(name: "analyst", system_prompt: "Analyze data.")
+manager = RobotLab.build(name: "manager", system_prompt: "Coordinate work.")
+
+result = manager.delegate(to: analyst, task: "Summarize the Q3 report.")
+puts result.reply
+puts "Completed in %.2fs using %d tokens" % [result.duration, result.output_tokens]
+puts result.delegated_by  # => "manager"
+```
+
+### Asynchronous Delegation (Fan-out)
+
+Pass `async: true` to get a `DelegationFuture` back immediately. Call `.value` to block for the result when you need it.
+
+```ruby
+writer  = RobotLab.build(name: "writer",  system_prompt: "Write clearly.")
+analyst = RobotLab.build(name: "analyst", system_prompt: "Analyze data.")
+manager = RobotLab.build(name: "manager", system_prompt: "Coordinate.")
+
+# Fan out — both start immediately
+f1 = manager.delegate(to: analyst, task: "Analyze Q3 numbers", async: true)
+f2 = manager.delegate(to: writer,  task: "Draft the intro paragraph", async: true)
+
+# ... do other work here ...
+
+# Collect results (blocks if not yet done)
+analysis = f1.value
+draft    = f2.value
+
+# With a timeout (raises DelegationFuture::DelegationTimeout)
+result = f1.value(timeout: 30)
+```
+
+`DelegationFuture` API:
+
+| Method | Description |
+|--------|-------------|
+| `resolved?` | Non-blocking poll — true if completed or errored |
+| `value(timeout: nil)` | Block until done; re-raises any error from the delegatee |
+| `wait` | Alias for `value` |
+| `robot_name` | Name of the robot that was delegated to |
+| `delegated_by` | Name of the robot that created this future |
+
 ## Configuration
 
 RobotLab uses `MywayConfig` for configuration. Access the config object directly -- there is no `RobotLab.configure` block:

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