robot_lab 0.0.12 → 0.2.1

data/examples/32_newsletter_reader.rb

@@ -0,0 +1,188 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 32: Newsletter Issue Retriever
+#
+# Fetches all unprocessed issues from multiple Ruby newsletters via RSS
+# and saves each as a Markdown file in the Obsidian Clippings folder.
+#
+# - Processes oldest unprocessed issue first (across all feeds)
+# - Filename: <newsletter-name>_YYYYMMDD.md
+# - Includes YAML frontmatter with source URL (compatible with Clippings workflow)
+# - Tracks processed issue URLs in ~/.robot_lab/newsletter_processed.yaml
+#
+# Usage:
+#   ruby examples/32_newsletter_reader.rb
+
+require "net/http"
+require "open3"
+require "time"
+require "uri"
+require "yaml"
+require "fileutils"
+require "rexml/document"
+require "rexml/xpath"
+
+NEWSLETTER_RSS_URLS = [
+  "https://rss.beehiiv.com/feeds/MTJunJRFxo.xml",       # Ruby AI News
+  "https://cprss.s3.amazonaws.com/rubyweekly.com.xml"   # Ruby Weekly
+].freeze
+
+CLIPPINGS_DIR        = File.expand_path("/Users/dewayne/Documents/obsidian_order_intelligence/PKM/Clippings")
+PROCESSED_STATE_FILE = File.join(Dir.home, ".robot_lab", "newsletter_processed.yaml")
+
+# Tracks which newsletter issue URLs have been saved.
+class ProcessedIssues
+  def initialize(path: PROCESSED_STATE_FILE)
+    @path = path
+    @urls = load_urls
+  end
+
+  def processed?(url)
+    @urls.include?(url)
+  end
+
+  def mark_processed(url)
+    @urls << url
+    FileUtils.mkdir_p(File.dirname(@path))
+    File.write(@path, YAML.dump(@urls.uniq))
+  end
+
+  def count = @urls.size
+
+  private
+
+  def load_urls
+    return [] unless File.exist?(@path)
+    Array(YAML.safe_load(File.read(@path)) || [])
+  end
+end
+
+# Fetches a single RSS feed URL and returns its items (unsorted).
+# Each item: { title:, url:, pub_date:, published_at:, html:, channel_name: }
+def fetch_rss_items(url)
+  uri      = URI(url)
+  response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |h| h.get(uri.request_uri) }
+  raise "HTTP #{response.code}: #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+  doc  = REXML::Document.new(response.body)
+  ns   = { "content" => "http://purl.org/rss/1.0/modules/content/" }
+
+  channel_title = REXML::XPath.first(doc, "//channel/title")&.text&.strip || "newsletter"
+
+  REXML::XPath.match(doc, "//channel/item").filter_map do |item|
+    item_url = REXML::XPath.first(item, "link")&.text&.strip
+    title    = REXML::XPath.first(item, "title")&.text&.strip
+    pub_date = REXML::XPath.first(item, "pubDate")&.text&.strip
+    html     = REXML::XPath.first(item, "content:encoded", ns)&.text ||
+               REXML::XPath.first(item, "description")&.text || ""
+
+    next unless item_url && title && pub_date
+
+    {
+      title:        title,
+      url:          item_url,
+      pub_date:     pub_date,
+      published_at: Time.parse(pub_date),
+      html:         html,
+      channel_name: channel_title
+    }
+  end
+end
+
+# Fetches all configured RSS feeds and returns items sorted oldest-first.
+def fetch_all_rss_items
+  NEWSLETTER_RSS_URLS.flat_map do |feed_url|
+    print "  #{feed_url}... "
+    items = fetch_rss_items(feed_url)
+    puts "#{items.size} issues"
+    items
+  end.sort_by { |item| item[:published_at] }
+end
+
+# Converts HTML to Markdown via html2markdown CLI, stripping UTM params.
+def html_to_markdown(html)
+  md, = Open3.capture3(
+    "html2markdown",
+    stdin_data: html
+  )
+  md.gsub(/\]\(([^)]+)\)/) do
+    url = $1
+    if url.include?("?")
+      base, query = url.split("?", 2)
+      kept = query.split("&").reject { |p| p.start_with?("utm_") }
+      "](#{kept.empty? ? base : "#{base}?#{kept.join("&")}"})"
+    else
+      "](#{url})"
+    end
+  end
+end
+
+# Builds the output filename: <newsletter-name>_YYYYMMDD.md
+def output_filename(channel_name, published_at)
+  safe_name = channel_name.downcase.gsub(/[^a-z0-9]+/, "_").delete_suffix("_")
+  date_str  = published_at.strftime("%Y%m%d")
+  "#{safe_name}_#{date_str}.md"
+end
+
+# Wraps markdown content in YAML frontmatter compatible with the Clippings workflow.
+def wrap_with_frontmatter(title:, url:, pub_date:, body:)
+  date = Time.parse(pub_date).strftime("%Y-%m-%d")
+  <<~MD
+    ---
+    source: #{url}
+    title: "#{title.gsub('"', '\\"')}"
+    date: #{date}
+    ---
+
+    # #{title}
+
+    #{body.strip}
+  MD
+end
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+puts "=" * 60
+puts "Example 32: Newsletter Issue Retriever"
+puts "=" * 60
+puts
+
+FileUtils.mkdir_p(CLIPPINGS_DIR)
+state = ProcessedIssues.new
+
+puts "Fetching #{NEWSLETTER_RSS_URLS.size} RSS feeds..."
+all_items = fetch_all_rss_items
+pending   = all_items.reject { |item| state.processed?(item[:url]) }
+puts "#{all_items.size} total issues found across all feeds."
+
+if pending.empty?
+  puts "All issues already saved. Nothing to do."
+  exit
+end
+
+puts "#{pending.size} unprocessed (#{state.count} already done). Saving oldest-first."
+puts
+
+pending.each_with_index do |item, idx|
+  filename = output_filename(item[:channel_name], item[:published_at])
+  filepath = File.join(CLIPPINGS_DIR, filename)
+
+  print "[#{idx + 1}/#{pending.size}] #{item[:title]} (#{item[:published_at].strftime("%Y-%m-%d")})... "
+
+  body     = html_to_markdown(item[:html])
+  content  = wrap_with_frontmatter(
+    title:    item[:title],
+    url:      item[:url],
+    pub_date: item[:pub_date],
+    body:     body
+  )
+
+  File.write(filepath, content)
+  state.mark_processed(item[:url])
+
+  puts "saved → #{filename}"
+end
+
+puts
+puts "Done. #{pending.size} issue(s) saved to #{CLIPPINGS_DIR}"

data/examples/33_stock_generator.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 33: XYZZY Stock Price Generator
+#
+# Publishes fake streaming prices for ticker XYZZY to a Redis channel
+# using Geometric Brownian Motion with occasional volatility regime shifts.
+#
+# Prerequisites:
+#   gem install redis
+#   Redis server running on localhost:6379
+#
+# Usage:
+#   ruby examples/33_stock_generator.rb
+
+require "redis"
+require "json"
+require "time"
+
+CHANNEL     = "stock:xyzzy"
+START_PRICE = 100.0
+BASE_VOL    = 0.008   # baseline volatility per tick (~0.8%)
+DRIFT       = 0.0001  # slight upward drift per tick
+
+# Box-Muller transform — standard normal sample
+def randn
+  Math.sqrt(-2.0 * Math.log(rand)) * Math.cos(2.0 * Math::PI * rand)
+end
+
+# Occasionally shift the volatility regime to create interesting price dynamics
+def current_volatility(tick)
+  case tick % 60
+  when 0..10  then BASE_VOL * 2.0   # high volatility burst
+  when 30..35 then BASE_VOL * 0.4   # low volatility squeeze
+  else             BASE_VOL
+  end
+end
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+redis = Redis.new
+price = START_PRICE
+tick  = 0
+
+trap("INT") { puts "\nGenerator stopped."; exit }
+
+puts "=" * 50
+puts "XYZZY Stock Generator"
+puts "=" * 50
+puts "Channel : #{CHANNEL}"
+puts "Interval: 5 seconds per tick"
+puts "Model   : Geometric Brownian Motion"
+puts "Press Ctrl-C to stop."
+puts "-" * 50
+
+loop do
+  tick += 1
+
+  vol   = current_volatility(tick)
+  price = (price * Math.exp((DRIFT - 0.5 * vol**2) + vol * randn)).round(2)
+  price = [price, 1.0].max  # floor at $1.00
+
+  regime = case vol
+           when BASE_VOL * 2.0 then " [HIGH VOL]"
+           when BASE_VOL * 0.4 then " [low vol]"
+           else ""
+           end
+
+  payload = JSON.generate(
+    ticker:    "XYZZY",
+    price:     price,
+    tick:      tick,
+    timestamp: Time.now.iso8601
+  )
+
+  redis.publish(CHANNEL, payload)
+  puts "Tick %5d  $%8.2f  vol=%.3f%s" % [tick, price, vol, regime]
+
+  sleep 5
+end

data/examples/33_stock_predictor.rb

@@ -0,0 +1,306 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 33: XYZZY Stock Price Predictor
+#
+# Consumes fake streaming prices for ticker XYZZY from a Redis channel,
+# predicts the high and low over the next price window using an SMA + EMA
+# ensemble, and uses a RobotLab learning robot to tune predictor parameters
+# after each window closes.
+#
+# Run alongside:
+#   ruby examples/33_stock_generator.rb   (in a separate terminal)
+#
+# Prerequisites:
+#   gem install redis
+#   Redis server running on localhost:6379
+#
+# Usage:
+#   ruby examples/33_stock_predictor.rb
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "robot_lab"
+require "robot_lab/durable"
+require "redis"
+require "json"
+
+CHANNEL     = "stock:xyzzy"
+WINDOW_SIZE = 12  # ticks per prediction window
+
+# ── Mutable predictor parameters ──────────────────────────────────────────────
+
+module PredictorConfig
+  @sma_window         = 10
+  @sma_std_multiplier = 1.5
+  @ema_alpha          = 0.2
+  @ema_vol_multiplier = 2.0
+  @sma_weight         = 0.5
+
+  class << self
+    attr_accessor :sma_window, :sma_std_multiplier, :ema_alpha,
+                  :ema_vol_multiplier, :sma_weight
+
+    def summary
+      format(
+        "sma_window=%d  sma_std=%.2f  ema_alpha=%.2f  ema_vol=%.2f  sma_weight=%.2f",
+        sma_window, sma_std_multiplier, ema_alpha, ema_vol_multiplier, sma_weight
+      )
+    end
+  end
+end
+
+# ── SMA predictor ──────────────────────────────────────────────────────────────
+
+module SMAPredictor
+  def self.predict(prices)
+    window = prices.last(PredictorConfig.sma_window)
+    mean   = window.sum / window.size.to_f
+    var    = window.sum { |p| (p - mean)**2 } / window.size.to_f
+    std    = Math.sqrt(var)
+    mult   = PredictorConfig.sma_std_multiplier
+
+    {
+      high: (mean + mult * std).round(2),
+      low:  [mean - mult * std, 1.0].max.round(2)
+    }
+  end
+end
+
+# ── EMA predictor (stateful — updated every tick) ──────────────────────────────
+
+module EMAPredictor
+  @ema     = nil
+  @var_ema = nil
+
+  class << self
+    def update(price)
+      alpha = PredictorConfig.ema_alpha
+      if @ema.nil?
+        @ema     = price
+        @var_ema = 0.0
+      else
+        delta    = price - @ema
+        @ema     = alpha * price + (1 - alpha) * @ema
+        @var_ema = alpha * delta**2 + (1 - alpha) * @var_ema
+      end
+    end
+
+    def predict
+      return nil if @ema.nil?
+
+      vol = Math.sqrt(@var_ema) * PredictorConfig.ema_vol_multiplier
+      {
+        high: (@ema + vol).round(2),
+        low:  [@ema - vol, 1.0].max.round(2)
+      }
+    end
+  end
+end
+
+# ── Ensemble predictor ─────────────────────────────────────────────────────────
+
+module EnsemblePredictor
+  def self.predict(prices)
+    sma = SMAPredictor.predict(prices)
+    ema = EMAPredictor.predict
+    return sma unless ema
+
+    w = PredictorConfig.sma_weight
+    {
+      high: (w * sma[:high] + (1 - w) * ema[:high]).round(2),
+      low:  (w * sma[:low]  + (1 - w) * ema[:low]).round(2)
+    }
+  end
+end
+
+# ── AdjustParameters tool ──────────────────────────────────────────────────────
+
+class AdjustParameters < RobotLab::Tool
+  description "Adjust one predictor parameter to improve future prediction accuracy. " \
+              "Make at most one or two targeted changes per window."
+
+  param :parameter, type: "string",
+    desc: "Parameter to adjust: sma_window, sma_std_multiplier, ema_alpha, ema_vol_multiplier, sma_weight"
+  param :value, type: "number",
+    desc: "New value (sma_window: 3-30 int; std/vol multipliers: 0.5-4.0; ema_alpha: 0.05-0.5; sma_weight: 0.0-1.0)"
+  param :reasoning, type: "string",
+    desc: "Why this change should reduce prediction error"
+
+  LIMITS = {
+    "sma_window"         => { min: 3,    max: 30,  integer: true  },
+    "sma_std_multiplier" => { min: 0.5,  max: 4.0, integer: false },
+    "ema_alpha"          => { min: 0.05, max: 0.5, integer: false },
+    "ema_vol_multiplier" => { min: 0.5,  max: 4.0, integer: false },
+    "sma_weight"         => { min: 0.0,  max: 1.0, integer: false }
+  }.freeze
+
+  def execute(parameter:, value:, reasoning:)
+    spec = LIMITS[parameter]
+    return "Unknown parameter '#{parameter}'. Valid: #{LIMITS.keys.join(", ")}" unless spec
+
+    clamped = value.to_f.clamp(spec[:min], spec[:max])
+    clamped = clamped.round if spec[:integer]
+
+    PredictorConfig.send(:"#{parameter}=", clamped)
+
+    "Set #{parameter} = #{clamped}. #{reasoning}"
+  end
+end
+
+# ── Error metrics ──────────────────────────────────────────────────────────────
+
+WindowResult = Data.define(
+  :window_num,
+  :predicted_high, :predicted_low,
+  :actual_high,    :actual_low,
+  :high_err,       :low_err,       :mean_err
+)
+
+def evaluate_window(window_num, predicted, actuals)
+  actual_high = actuals.max.round(2)
+  actual_low  = actuals.min.round(2)
+  high_err    = (predicted[:high] - actual_high).abs.round(2)
+  low_err     = (predicted[:low]  - actual_low).abs.round(2)
+  mean_err    = ((high_err + low_err) / 2.0).round(2)
+
+  WindowResult.new(
+    window_num:,
+    predicted_high: predicted[:high], predicted_low: predicted[:low],
+    actual_high:,   actual_low:,
+    high_err:,      low_err:,         mean_err:
+  )
+end
+
+def tuner_prompt(result)
+  <<~PROMPT
+    Window #{result.window_num} just closed.
+
+    Prediction vs Actual:
+      Predicted: high=$#{result.predicted_high}  low=$#{result.predicted_low}
+      Actual:    high=$#{result.actual_high}      low=$#{result.actual_low}
+      Error:     high_err=$#{result.high_err}  low_err=$#{result.low_err}  mean_err=$#{result.mean_err}
+
+    Current parameters:
+      #{PredictorConfig.summary}
+
+    Window size: #{WINDOW_SIZE} ticks.
+
+    First call RecallKnowledge to check what has worked before.
+    Then decide whether to adjust a parameter via AdjustParameters.
+    If the error is acceptable or you are uncertain, do nothing.
+    If you notice a clear pattern worth preserving, call RecordKnowledge.
+  PROMPT
+end
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+puts "=" * 60
+puts "XYZZY Stock Predictor"
+puts "=" * 60
+puts "Channel    : #{CHANNEL}"
+puts "Window     : #{WINDOW_SIZE} ticks"
+puts "Model      : SMA + EMA Ensemble with Durable Learning"
+puts "Warmup     : #{PredictorConfig.sma_window} ticks"
+puts "Press Ctrl-C to stop."
+puts "-" * 60
+
+redis      = Redis.new
+prices     = []
+robot      = RobotLab.build(
+  model: "gpt-5.4",
+               name:          "predictor_tuner",
+               system_prompt: <<~PROMPT,
+                 You are a quantitative analyst tuning an ensemble stock price range
+                 predictor for ticker XYZZY. Each prediction covers the high and low
+                 price over the next #{WINDOW_SIZE} ticks.
+
+                 The ensemble combines a Simple Moving Average (SMA) band and an
+                 Exponential Moving Average (EMA) band. Adjustable parameters:
+
+                   sma_window (3-30 int)         — lookback period for SMA
+                   sma_std_multiplier (0.5-4.0)  — band width relative to SMA stddev
+                   ema_alpha (0.05-0.5)           — EMA smoothing (higher = more reactive)
+                   ema_vol_multiplier (0.5-4.0)   — band width relative to EMA volatility
+                   sma_weight (0.0-1.0)           — SMA share in ensemble (EMA = 1 - weight)
+
+                 Workflow per window:
+                   1. Call RecallKnowledge to check past findings before acting.
+                   2. If the error is clearly too high/low in one direction, adjust the
+                      relevant band multiplier via AdjustParameters.
+                   3. Make at most two adjustments per window to isolate cause and effect.
+                   4. If you observe a reliable pattern, call RecordKnowledge to preserve it.
+                   5. When uncertain, do nothing rather than guess.
+               PROMPT
+               local_tools:   [AdjustParameters],
+               learn:         true,
+               learn_domain:  "xyzzy stock prediction"
+             )
+
+warmed_up    = false
+pending_pred = nil  # { prediction: {high:, low:}, window_prices: [] }
+window_num   = 0
+
+trap("INT") { puts "\nPredictor stopped."; exit }
+
+puts "Connecting to Redis and subscribing to #{CHANNEL}..."
+
+redis.subscribe(CHANNEL) do |on|
+  on.message do |_channel, payload|
+    data  = JSON.parse(payload, symbolize_names: true)
+    tick  = data[:tick]
+    price = data[:price].to_f
+
+    EMAPredictor.update(price)
+    prices << price
+
+    # ── Warmup phase ──────────────────────────────────────────────
+    unless warmed_up
+      if prices.size < PredictorConfig.sma_window
+        puts "Tick %5d  $%8.2f  [warming up %d/%d]" % [tick, price, prices.size, PredictorConfig.sma_window]
+        next
+      end
+
+      warmed_up    = true
+      pred         = EnsemblePredictor.predict(prices)
+      pending_pred = { prediction: pred, window_prices: [] }
+
+      puts "Tick %5d  $%8.2f  [warmup done]" % [tick, price]
+      puts "  First prediction → high=$#{pred[:high]}  low=$#{pred[:low]}"
+      next
+    end
+
+    # ── Accumulate current window ──────────────────────────────────
+    pending_pred[:window_prices] << price
+    progress = pending_pred[:window_prices].size
+    pred     = pending_pred[:prediction]
+
+    puts "Tick %5d  $%8.2f  [%2d/#{WINDOW_SIZE}]  (pred high=$#{pred[:high]} low=$#{pred[:low]})" %
+         [tick, price, progress]
+
+    next unless progress >= WINDOW_SIZE
+
+    # ── Window closed — evaluate ───────────────────────────────────
+    window_num += 1
+    result = evaluate_window(window_num, pred, pending_pred[:window_prices])
+
+    puts "\n#{"─" * 60}"
+    puts "  Window #{result.window_num} result:"
+    puts "    Predicted  high=$%-8.2f  low=$%-.2f" % [result.predicted_high, result.predicted_low]
+    puts "    Actual     high=$%-8.2f  low=$%-.2f" % [result.actual_high, result.actual_low]
+    puts "    Error      high=%-8.2f  low=%-8.2f  mean=%.2f" % [result.high_err, result.low_err, result.mean_err]
+    puts "#{"─" * 60}"
+
+    print "  [tuner] analyzing window #{window_num}..."
+    tuner_response = robot.run(tuner_prompt(result))
+    tuner_line     = tuner_response.reply.lines.first&.chomp || "(no response)"
+    puts "\r  [tuner] #{tuner_line}#{" " * 20}"
+    puts "  Params: #{PredictorConfig.summary}"
+    puts
+
+    # ── Start next window ──────────────────────────────────────────
+    new_pred     = EnsemblePredictor.predict(prices)
+    pending_pred = { prediction: new_pred, window_prices: [] }
+    puts "  Next prediction → high=$#{new_pred[:high]}  low=$#{new_pred[:low]}"
+    puts
+  end
+end

data/examples/34_agentskills.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 34: AgentSkills.io Integration
+#
+# Demonstrates the unified skills: param detecting AgentSkills folder format.
+# Skills in ~/.prompts/skills/ are matched at runtime via embedding similarity
+# before each run() call — only relevant skills are injected.
+#
+# Usage:
+#   mkdir -p ~/.prompts/skills/code_reviewer
+#   # (create SKILL.md as shown in the example header)
+#   ANTHROPIC_API_KEY=your_key ruby examples/34_agentskills.rb
+
+require_relative "common"
+
+require "logger"
+log_file = File.join(__dir__, "34.log")
+RobotLab.config.logger = Logger.new(log_file)
+RubyLLM.configure { |c| c.logger = Logger.new(log_file) }
+
+banner "RobotLab — AgentSkills.io Integration Demo"
+
+# Check if the skill is installed
+skill_path = File.expand_path("~/.prompts/skills/code_reviewer/SKILL.md")
+unless File.exist?(skill_path)
+  puts "Demo skill not found at #{skill_path}"
+  puts "Create it with:"
+  puts "  mkdir -p ~/.prompts/skills/code_reviewer"
+  puts "  # Then add SKILL.md with name: code_reviewer"
+  exit 1
+end
+
+# Build a robot that lists code_reviewer as a candidate skill.
+# At runtime, if the user message is semantically similar to
+# "Review Ruby code for quality, style, and potential bugs",
+# the skill's instructions are injected into the system prompt.
+robot = RobotLab.build(
+  model: LLM[:default].model,
+  name: "assistant",
+  system_prompt: "You are a helpful Ruby programming assistant.",
+  skills: [:code_reviewer]
+)
+
+puts "Pending AgentSkills: #{robot.instance_variable_get(:@pending_agent_skills).map(&:name).inspect}"
+puts
+
+# Message semantically related to code review — skill should activate
+code_question = <<~MSG
+  Please review this Ruby method for quality issues:
+
+  def process(data)
+    begin
+      result = data.map { |item| transform(item) }
+      save(result)
+    rescue => e
+      puts e.message
+    end
+  end
+MSG
+
+puts "Query: code review (skill should activate)"
+result = robot.run(code_question)
+puts result.reply
+puts
+hr
+
+# Message unrelated to code review — skill should NOT activate
+puts "Query: general question (skill should NOT activate)"
+result = robot.run("What is the capital of France?")
+puts result.reply
+puts

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
@@ -225,7 +226,7 @@ Demonstrates `robot.search_history(query, limit:)` — semantic search over accu
 
 Demonstrates `memory.store_document(key, text)` and `memory.search_documents(query, limit:)` — a lightweight RAG store using `fastembed` (BAAI/bge-small-en-v1.5). Documents are embedded once; queries are compared by cosine similarity at search time. Includes the `RobotLab::DocumentStore` standalone API and a RAG pattern sketch showing how to pass retrieved context to a robot.
 
-**Requires:** `fastembed` gem (already a core dependency); downloads the ~23 MB ONNX model on first run (cached in `~/.cache/fastembed/`)
+**Requires:** `robot_lab-document_store` gem (`gem "robot_lab-document_store"` in your Gemfile); downloads the ~23 MB ONNX model on first run (cached in `~/.cache/fastembed/`)
 
 ### 27 — Production Incident War Room
 
@@ -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.