robot_lab 0.0.9 → 0.0.11

data/examples/27_incident_response/incident_response.rb

@@ -0,0 +1,244 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 27: Production Incident War Room
+#
+# A payment-service outage is in progress. Three SRE scouts investigate
+# different layers in parallel — database, network, and application. Each
+# scout writes findings to shared reactive memory and broadcasts a status
+# update to the war-room coordinator via TypedBus.
+#
+# Phase 5 infrastructure features demonstrated:
+#
+#   REACTIVE MEMORY  (IO.pipe Waiter — #13)
+#   ──────────────────────────────────────────────────────────────
+#   db_scout   ─┐  memory[:db_finding] = "..."  ─┐
+#   net_scout  ─┼  memory[:net_finding] = "..." ─┼→ IO.pipe signal
+#   app_scout  ─┘  memory[:app_finding] = "..." ─┘
+#                                                  ↓
+#                     commander.get(:db_finding, :net_finding, :app_finding, wait: 60)
+#                     wakes via IO.select on the pipe — no busy-wait, Async-safe
+#
+#   BUS POLLER  (serialized delivery — #14)
+#   ──────────────────────────────────────────────────────────────
+#   db_scout, net_scout, app_scout each send a bus message to :war_room.
+#   If two scouts finish simultaneously, their deliveries queue in BusPoller
+#   so war_room processes them one at a time — no re-entrancy, no dropped
+#   messages, arrival order preserved.
+#
+#   POLLER GROUPS  (#15)
+#   ──────────────────────────────────────────────────────────────
+#   task :db_scout,  poller_group: :investigation   (fast, no LLM in final stage)
+#   task :net_scout, poller_group: :investigation
+#   task :app_scout, poller_group: :investigation
+#   task :commander, poller_group: :command         (expensive synthesis call)
+#
+# Usage:
+#   bundle exec ruby examples/27_incident_response/incident_response.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "../prompts")
+
+require_relative "../../lib/robot_lab"
+require "fileutils"
+
+RubyLLM.configure { |c| c.logger = Logger.new(File::NULL) }
+
+OUTPUT_DIR = File.join(__dir__, "output")
+FileUtils.mkdir_p(OUTPUT_DIR)
+
+# ── Scout ──────────────────────────────────────────────────────────────────
+#
+# Investigates one subsystem, stores a terse finding in shared memory,
+# and broadcasts a status line to the war-room via bus.
+#
+# NOTE: we bypass extract_run_context's delete() pattern and hold a direct
+# reference to shared memory — the same technique used in example 15 —
+# because parallel pipeline steps would otherwise lose the memory reference
+# after the first step runs.
+
+class SREScout < RobotLab::Robot
+  attr_writer :shared_memory
+
+  def initialize(name:, subsystem:, memory_key:, bus: nil)
+    super(
+      name: name,
+      system_prompt: "You are a senior SRE responding to a production outage. " \
+                     "Diagnose one infrastructure layer in 2 sentences: " \
+                     "first sentence is root cause, second is customer impact.",
+      bus: bus
+    )
+    @subsystem  = subsystem
+    @memory_key = memory_key
+  end
+
+  def call(result)
+    incident = extract_message(result)
+
+    finding = run("Investigate the #{@subsystem} layer. #{incident}").reply.strip
+
+    # Write to reactive memory — wakes the IO.pipe waiter in the commander
+    if @shared_memory
+      @shared_memory.current_writer = name
+      @shared_memory.set(@memory_key, finding)
+    end
+
+    puts "  [#{name}] #{finding[0..100]}#{"..." if finding.length > 100}"
+
+    # Notify war room — BusPoller queues this if war_room is already processing
+    send_message(to: :war_room, content: "[#{@subsystem}] #{finding}") if bus
+
+    result.with_context(name.to_sym, finding).continue(finding)
+  end
+
+  private
+
+  def extract_message(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
+
+# ── War Room ───────────────────────────────────────────────────────────────
+#
+# Receives scout status updates via TypedBus.
+# BusPoller serializes delivery: even if all three scouts finish at the
+# same instant their messages are processed one at a time and none is
+# dropped.  Delivery order is preserved by the queue.
+
+class WarRoom < RobotLab::Robot
+  attr_reader :updates
+
+  def initialize(bus:)
+    super(name: "war_room", system_prompt: "SRE war-room coordinator.", bus: bus)
+    @updates        = []
+    @delivery_mutex = Mutex.new  # only for reading @updates outside Async
+
+    on_message do |msg|
+      # BusPoller ensures this block is never re-entered for the same robot.
+      # Simulate brief processing work so a second delivery would have to queue.
+      @updates << msg.content
+      puts "  [war_room] Update ##{@updates.size} processed: #{msg.content[0..70]}..."
+    end
+  end
+end
+
+# ── Incident Commander ─────────────────────────────────────────────────────
+#
+# Waits until all three scout findings land in shared memory, then calls
+# the LLM once to synthesize an action plan.
+#
+# memory.get(:db_finding, :net_finding, :app_finding, wait: 60)
+#   → internally each key uses an IO.pipe-backed Waiter
+#   → IO.select wakes the call as soon as all three keys are written
+#   → no busy-wait, no mutex spin, works cleanly with Async
+
+class IncidentCommander < RobotLab::Robot
+  attr_writer :shared_memory
+
+  def call(result)
+    puts "  [commander] Blocking on reactive memory — waiting for all scout findings..."
+
+    findings = @shared_memory.get(:db_finding, :net_finding, :app_finding, wait: 60)
+
+    if findings.values.include?(:timeout)
+      timed_out = findings.select { |_k, v| v == :timeout }.keys
+      puts "  [commander] WARNING: scouts timed out: #{timed_out.join(", ")}"
+    end
+
+    prompt = <<~PROMPT
+      Three SRE scouts have reported their findings for a payment-service outage.
+      Issue a concise incident action plan (3–5 bullet points) covering immediate
+      mitigation, next investigation steps, and stakeholder communication.
+
+      Database layer: #{findings[:db_finding] || "no data"}
+      Network layer:  #{findings[:net_finding] || "no data"}
+      Application:    #{findings[:app_finding] || "no data"}
+    PROMPT
+
+    report = run(prompt).reply.strip
+
+    @shared_memory[:incident_report] = report
+
+    path = File.join(OUTPUT_DIR, "incident_report.md")
+    File.write(path, "# Incident Action Plan\n\n#{report}\n")
+    puts "  [commander] Action plan written to #{path}"
+
+    result.with_context(:commander, report).continue(report)
+  end
+end
+
+# ── Wire up ────────────────────────────────────────────────────────────────
+
+bus = TypedBus::MessageBus.new
+
+db_scout  = SREScout.new(name: "db_scout",  subsystem: "database",    memory_key: :db_finding,  bus: bus)
+net_scout = SREScout.new(name: "net_scout", subsystem: "network",     memory_key: :net_finding, bus: bus)
+app_scout = SREScout.new(name: "app_scout", subsystem: "application", memory_key: :app_finding, bus: bus)
+war_room  = WarRoom.new(bus: bus)
+commander = IncidentCommander.new(name: "commander", system_prompt: "SRE incident commander.")
+
+# Build the investigation network
+# poller_group: labels are registered on the network's shared BusPoller.
+network = RobotLab.create_network(name: "incident_response") do
+  task :db_scout,  db_scout,  depends_on: :none, poller_group: :investigation
+  task :net_scout, net_scout, depends_on: :none, poller_group: :investigation
+  task :app_scout, app_scout, depends_on: :none, poller_group: :investigation
+  task :commander, commander, depends_on: [:db_scout, :net_scout, :app_scout], poller_group: :command
+end
+
+# Assign direct shared-memory references (avoids the extract_run_context
+# mutation problem with parallel pipeline steps — see example 15).
+shared_memory = network.memory
+[db_scout, net_scout, app_scout, commander].each do |r|
+  r.shared_memory = shared_memory
+end
+
+# Subscribe to memory changes — fires as each scout writes its finding.
+# The callback runs asynchronously; the IO.pipe waiter in commander wakes
+# independently when the key is set.
+network.memory.subscribe(:db_finding, :net_finding, :app_finding) do |change|
+  puts "  [memory] :#{change.key} written by #{change.writer}"
+end
+
+# ── Run ────────────────────────────────────────────────────────────────────
+
+puts "=" * 65
+puts "Example 27: Production Incident War Room"
+puts "  Phase 5 — BusPoller · Reactive Memory · Poller Groups"
+puts "=" * 65
+puts
+puts network.visualize
+puts
+
+puts "Poller groups registered on network BusPoller:"
+puts "  #{network.instance_variable_get(:@bus_poller).groups.inspect}"
+puts
+
+puts "INCIDENT: Payment service degraded — elevated error rates and timeouts"
+puts "-" * 65
+puts
+
+result = network.run(message: "Payment service is degraded: elevated HTTP 500 " \
+                               "error rates (~12%) and p99 latency spiked to 8s. " \
+                               "Investigate your assigned infrastructure layer.")
+
+puts
+puts "-" * 65
+puts "War-room updates received (BusPoller order):"
+war_room.updates.each.with_index(1) { |u, i| puts "  #{i}. #{u.gsub(/\s+/, " ")[0..90]}" }
+puts
+puts "Reactive memory keys written by scouts:"
+%i[db_finding net_finding app_finding].each do |key|
+  val = network.memory[key]
+  puts "  :#{key.to_s.ljust(14)} #{val&.gsub(/\s+/, " ")&.slice(0, 80)}..."
+end
+puts
+puts "Incident action plan (from #{OUTPUT_DIR}/incident_report.md):"
+puts "-" * 65
+report = network.memory[:incident_report].to_s
+puts report
+puts
+puts "=" * 65

data/examples/28_mcp_discovery.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 28: MCP Server Discovery
+#
+# When a robot has many MCP servers configured, connecting to all of them
+# upfront is wasteful — some servers may be irrelevant to a particular query.
+#
+# MCP Server Discovery uses TF cosine similarity to select only the servers
+# semantically relevant to the user's query, then connects only those.
+#
+# == Key config
+#
+#   robot = RobotLab.build(
+#     mcp_discovery: true,    # ← enables semantic filtering
+#     mcp: [ ... ]            # ← candidate servers, each with :description
+#   )
+#
+# == Fallback behaviour
+#
+#   All servers are connected unchanged when:
+#   - No server has a :description field
+#   - The classifier gem is unavailable
+#   - The query is blank or nil
+#   - No server scores at or above the threshold (0.05 by default)
+#
+# This demo exercises MCP::ServerDiscovery directly — no LLM calls needed.
+#
+# Usage:
+#   bundle exec ruby examples/28_mcp_discovery.rb
+
+require_relative "../lib/robot_lab"
+
+# Three representative MCP server configurations
+SERVERS = [
+  {
+    name: "filesystem",
+    description: "Read, write, and search local files and directories",
+    transport: { type: "stdio", command: "mcp-server-filesystem" }
+  },
+  {
+    name: "github",
+    description: "GitHub repos, issues, pull requests, code search",
+    transport: { type: "stdio", command: "mcp-server-github" }
+  },
+  {
+    name: "brew",
+    description: "Install, update, and manage macOS packages via Homebrew",
+    transport: { type: "stdio", command: "mcp-server-brew" }
+  }
+].freeze
+
+def show_query(label, query)
+  selected = RobotLab::MCP::ServerDiscovery.select(query, from: SERVERS)
+  names    = selected.map { |s| s[:name] }
+
+  puts "  Query : #{query.inspect}"
+  puts "  Match : #{names.inspect}"
+  puts
+end
+
+puts "=" * 60
+puts "Example 28: MCP Server Discovery"
+puts "  Semantic server selection via TF cosine similarity"
+puts "=" * 60
+puts
+puts "Candidate servers:"
+SERVERS.each do |s|
+  puts "  #{s[:name].ljust(12)} #{s[:description]}"
+end
+puts
+
+puts "Discovery queries:"
+puts "-" * 60
+show_query("File ops",     "read my config file")
+show_query("Package mgmt", "install imagemagick via homebrew")
+show_query("Code review",  "list open pull requests on my repo")
+
+puts "Fallback cases:"
+puts "-" * 60
+
+# No description → all servers returned
+no_desc_servers = SERVERS.map { |s| s.except(:description) }
+result = RobotLab::MCP::ServerDiscovery.select("install imagemagick", from: no_desc_servers)
+puts "  No descriptions : returns all (#{result.size} servers)"
+
+# Blank query → all servers returned
+result = RobotLab::MCP::ServerDiscovery.select("", from: SERVERS)
+puts "  Blank query     : returns all (#{result.size} servers)"
+
+# Very high threshold → no match → fallback to all
+result = RobotLab::MCP::ServerDiscovery.select("install imagemagick", from: SERVERS, threshold: 1.0)
+puts "  High threshold  : returns all (#{result.size} servers) — no match above 1.0"
+
+puts
+puts "mcp_discovery: true on a Robot"
+puts "-" * 60
+puts <<~NOTE
+  RobotLab.build(
+    name: "assistant",
+    mcp_discovery: true,
+    mcp: [
+      { name: "filesystem", description: "Read, write...", transport: { ... } },
+      { name: "github",     description: "GitHub repos...", transport: { ... } },
+      { name: "brew",       description: "Install packages...", transport: { ... } }
+    ]
+  )
+
+  # Only the :brew server is connected for this message:
+  robot.run("install imagemagick")
+NOTE
+puts "=" * 60

data/examples/29_ractor_tools.rb

@@ -0,0 +1,243 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 29: Ractor-Safe CPU Tools
+#
+# Demonstrates Track 1 of RobotLab's Ractor parallelism: CPU-bound tools
+# that bypass Ruby's GVL by running inside a pool of Ractor workers.
+#
+# Concepts covered:
+#   - ractor_safe true  — opt a tool class into Ractor execution
+#   - Inheritance       — subclasses inherit ractor_safe automatically
+#   - RactorBoundary.freeze_deep — deep-freeze nested data before
+#                         crossing the Ractor boundary
+#   - RactorBoundaryError — raised for non-shareable values (Procs, IOs…)
+#   - RactorWorkerPool  — global pool, submit jobs, read frozen results
+#   - ToolError         — propagated when a tool raises inside a Ractor
+#   - Parallel batch    — many threads submitting concurrently vs sequentially
+#
+# Usage (no LLM API key required):
+#   bundle exec ruby examples/29_ractor_tools.rb
+#
+# Good to know:
+#   Ractor dispatch has a fixed overhead of ~20 ms per job (reply-queue
+#   Ractor creation + Ractor.make_shareable).  Computation must dominate
+#   that overhead for parallelism to win.  HeavyDigestTool uses 500 000
+#   SHA-256 rounds (~320 ms on modern hardware) so the 4-6× speedup is
+#   clearly visible on a 6-core machine.
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+require "digest"
+
+# Always shut down the pool when the process exits.
+at_exit { RobotLab.shutdown_ractor_pool }
+
+# =============================================================================
+# Tool definitions
+# =============================================================================
+
+# Base class — declare ractor_safe once; all subclasses inherit it.
+class TextTool < RobotLab::Tool
+  ractor_safe true
+end
+
+# Word and sentence statistics — pure computation, no shared state.
+class WordStatsTool < TextTool
+  description "Count words, sentences, and average word length"
+
+  param :text, type: :string, desc: "Text to analyze"
+
+  def execute(text:)
+    words     = text.scan(/\b\w+\b/)
+    sentences = [text.scan(/[.!?]+/).length, 1].max
+    avg_len   = words.empty? ? 0.0 : (words.sum(&:length).to_f / words.length).round(2)
+
+    { words: words.length, sentences: sentences, avg_word_len: avg_len }.freeze
+  end
+end
+
+# Words-per-sentence and long-word density (a simple readability proxy).
+class ReadabilityTool < TextTool
+  description "Estimate words-per-sentence and long-word density"
+
+  param :text, type: :string, desc: "Text to analyze"
+
+  def execute(text:)
+    words      = text.scan(/\b\w+\b/)
+    sentences  = [text.scan(/[.!?]+/).length, 1].max
+    long_words = words.count { |w| w.length > 6 }
+    long_pct   = words.empty? ? 0 : (long_words * 100 / words.length)
+
+    {
+      words:              words.length,
+      sentences:          sentences,
+      words_per_sentence: (words.length.to_f / sentences).round(1),
+      long_word_pct:      long_pct
+    }.freeze
+  end
+end
+
+# CPU-intensive: 500 000 SHA-256 rounds (~320 ms per job on modern hardware).
+# The overhead of reply-queue Ractor creation + make_shareable is ~20 ms per job
+# (constant), so computation must dwarf it to show a real speedup.
+class HeavyDigestTool < TextTool
+  description "SHA-256 chain (500 000 rounds) — CPU-intensive, Ractor-safe"
+
+  ROUNDS = 500_000
+
+  param :text, type: :string, desc: "Seed text"
+
+  def execute(text:)
+    digest = text
+    ROUNDS.times { digest = Digest::SHA256.hexdigest(digest) }
+    digest[0..15].freeze
+  end
+end
+
+# NOT Ractor-safe: @@hits is mutable class-level state.
+# Shown here purely as a contrast — do not submit this to the pool.
+class RequestCounterTool < RobotLab::Tool
+  description "Word count plus a mutable global call counter (not Ractor-safe)"
+
+  @@hits = 0   # mutable class variable — Ractor workers cannot access this
+
+  param :text, type: :string, desc: "Text to count"
+
+  def execute(text:)
+    @@hits += 1
+    "#{text.scan(/\b\w+\b/).length} words (total calls: #{@@hits})"
+  end
+end
+
+# =============================================================================
+# Demo
+# =============================================================================
+
+puts "=" * 62
+puts "Example 29: Ractor-Safe CPU Tools"
+puts "=" * 62
+puts
+
+DIVIDER = ("─" * 54).freeze
+
+SAMPLE_TEXTS = [
+  "Ruby makes programmer happiness a first-class concern in language design.",
+  "Ractors enable true CPU parallelism by isolating mutable state between actors.",
+  "Every distributed system eventually becomes a consistency problem.",
+  "The quick brown fox jumps over the lazy dog — a pangram.",
+  "Machine learning transforms raw observations into actionable insight.",
+  "Simplicity is the ultimate sophistication in software architecture."
+].freeze
+
+# ── 1. ractor_safe? flags ─────────────────────────────────────
+
+puts "1.  ractor_safe? flags"
+puts "    #{DIVIDER}"
+
+{
+  "WordStatsTool"     => WordStatsTool,
+  "ReadabilityTool"   => ReadabilityTool,
+  "HeavyDigestTool"   => HeavyDigestTool,
+  "RequestCounterTool" => RequestCounterTool
+}.each do |name, klass|
+  mark = klass.ractor_safe ? "✓ ractor_safe (inherits from TextTool)" : "✗ NOT ractor_safe"
+  puts "    #{name.ljust(22)}  #{mark}"
+end
+puts
+
+# ── 2. RactorBoundary.freeze_deep ─────────────────────────────
+
+puts "2.  RactorBoundary.freeze_deep"
+puts "    #{DIVIDER}"
+
+nested = { tags: ["ruby", "ractor"], meta: { version: 2 } }
+frozen = RobotLab::RactorBoundary.freeze_deep(nested)
+
+puts "    Input frozen?               #{nested.frozen?}"
+puts "    Output frozen?              #{frozen.frozen?}"
+puts "    Inner :tags array frozen?   #{frozen[:tags].frozen?}"
+puts "    Inner :meta hash frozen?    #{frozen[:meta].frozen?}"
+puts
+
+# A Proc cannot cross a Ractor boundary — freeze_deep raises immediately.
+require "stringio"
+begin
+  RobotLab::RactorBoundary.freeze_deep(StringIO.new("I cannot be frozen"))
+rescue RobotLab::RactorBoundaryError => e
+  puts "    RactorBoundaryError on StringIO:"
+  puts "    #{e.message.split('.').first}."
+end
+puts
+
+# ── 3. Single pool submissions ─────────────────────────────────
+
+pool = RobotLab.ractor_pool
+puts "3.  Worker pool  (#{pool.size} Ractors — one per CPU core)"
+puts "    #{DIVIDER}"
+
+sample = SAMPLE_TEXTS.first
+
+r = pool.submit("WordStatsTool",   { text: sample })
+puts "    WordStatsTool:   #{r.inspect}"
+
+r = pool.submit("ReadabilityTool", { text: sample })
+puts "    ReadabilityTool: words_per_sentence=#{r[:words_per_sentence]}  long_word_pct=#{r[:long_word_pct]}%"
+puts
+
+# ── 4. ToolError propagation ───────────────────────────────────
+
+puts "4.  ToolError propagation"
+puts "    #{DIVIDER}"
+puts "    Submitting nil as :text (WordStatsTool will call nil.scan — NoMethodError)"
+puts
+
+begin
+  pool.submit("WordStatsTool", { text: nil })
+rescue RobotLab::ToolError => e
+  puts "    RobotLab::ToolError caught:"
+  puts "    #{e.message}"
+end
+puts
+
+# ── 5. Parallel batch vs sequential ───────────────────────────
+
+puts "5.  Parallel batch — #{SAMPLE_TEXTS.length} jobs, each doing #{HeavyDigestTool::ROUNDS.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1_').reverse} SHA-256 rounds"
+puts "    #{DIVIDER}"
+
+# Parallel: one Thread per job, all submitted simultaneously.
+t0       = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+threads  = SAMPLE_TEXTS.map { |text| Thread.new { pool.submit("HeavyDigestTool", { text: text }) } }
+parallel_results = threads.map(&:value)
+parallel_time    = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+# Sequential: jobs submitted one-at-a-time from the main thread.
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+SAMPLE_TEXTS.each { |text| pool.submit("HeavyDigestTool", { text: text }) }
+seq_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+puts "    Parallel  (#{SAMPLE_TEXTS.length} threads → #{pool.size} Ractors): #{"%.3f" % parallel_time}s"
+puts "    Sequential (1 thread  → #{pool.size} Ractors): #{"%.3f" % seq_time}s"
+
+if seq_time > parallel_time * 1.2
+  puts "    Speedup: #{(seq_time / parallel_time).round(1)}×"
+else
+  puts "    Note: overhead (~20 ms/job for reply-queue Ractor + make_shareable)"
+  puts "    dominated this run. Increase ROUNDS further to widen the gap."
+end
+
+puts
+puts "    First result (truncated digest): #{parallel_results.first}"
+puts
+
+# ── 6. Shutdown ────────────────────────────────────────────────
+
+puts "6.  Shutdown"
+puts "    #{DIVIDER}"
+RobotLab.shutdown_ractor_pool
+puts "    Pool shut down cleanly (poison-pill × #{pool.size} workers)."
+puts
+puts "=" * 62
+puts "Example 29 complete."
+puts "=" * 62