robot_lab 0.3.0 → 0.3.1

data/examples/27_incident_response/incident_response.rb

@@ -1,261 +0,0 @@
-#!/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 "../common"
-require "fileutils"
-
-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,
-      **llm_opts,
-      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", **llm_opts, system_prompt: "SRE war-room coordinator.", bus: bus)
-    @updates = []
-
-    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
-
-  FINDING_KEYS = %i[db_finding net_finding app_finding].freeze
-
-  def call(result)
-    puts "  [commander] Blocking on reactive memory — waiting for all scout findings..."
-
-    findings = collect_findings
-
-    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
-
-  private
-
-  # Blocking multi-key read with a real degradation path.
-  #
-  # Memory#get(wait:) signals a timeout by RAISING RobotLab::AwaitTimeout — it
-  # never returns a :timeout sentinel value. Rescue it and re-read without
-  # wait:, which never blocks and simply omits keys that were never written,
-  # so a slow scout degrades the report instead of killing the commander.
-  def collect_findings
-    @shared_memory.get(*FINDING_KEYS, wait: 60)
-  rescue RobotLab::AwaitTimeout => e
-    puts "  [commander] WARNING: #{e.message}"
-    partial = @shared_memory.get(*FINDING_KEYS)
-    missing = FINDING_KEYS - partial.keys
-    puts "  [commander] Proceeding without: #{missing.join(', ')}" if missing.any?
-    partial
-  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", **llm_opts, 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 declared on the network's tasks:"
-puts "  :investigation — db_scout, net_scout, app_scout"
-puts "  :command       — commander"
-puts "(Network#task registers each group on the shared BusPoller; the poller"
-puts " itself is internal, so the groups are documented here rather than"
-puts " introspected.)"
-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

@@ -1,113 +0,0 @@
-#!/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(
-#     provider: "lms", model: "qwen/qwen3.8-27b",
-#     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 "common"
-
-# 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 "  #{label}"
-  puts "    Query : #{query.inspect}"
-  puts "    Match : #{names.inspect}"
-  puts
-end
-
-banner "MCP Server Discovery"
-puts "  Semantic server selection via TF cosine similarity"
-puts
-puts "Candidate servers:"
-SERVERS.each do |s|
-  puts "  #{s[:name].ljust(12)} #{s[:description]}"
-end
-puts
-
-section "Discovery Queries"
-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")
-
-section "Fallback Cases"
-
-# 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
-section "mcp_discovery: true on a Robot"
-show_code <<~RUBY
-  robot = RobotLab.build(
-    name:          "assistant",
-    provider:      "lms",
-    model:         "qwen3.6:latest",
-    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.
-  # mcp: :inherit and tools: :inherit are both required — run() defaults
-  # both to :none, which connects no servers and sends no tools.
-  robot.run("install imagemagick", mcp: :inherit, tools: :inherit)
-RUBY
-hr

data/examples/29_ractor_tools.rb

@@ -1,240 +0,0 @@
-#!/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 traffic — pure CPU work):
-#   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.
-
-require_relative "common"
-require "robot_lab/ractor"
-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"
-
-  parameter :text, type: :string, description: "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"
-
-  parameter :text, type: :string, description: "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
-
-  parameter :text, type: :string, description: "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
-
-  parameter :text, type: :string, description: "Text to count"
-
-  def execute(text:)
-    @@hits += 1
-    "#{text.scan(/\b\w+\b/).length} words (total calls: #{@@hits})"
-  end
-end
-
-# =============================================================================
-# Demo
-# =============================================================================
-
-banner "Ractor-Safe CPU Tools"
-
-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
-
-# Non-shareable objects (IO handles, Procs, ...) cannot cross a Ractor
-# boundary — freeze_deep rejects them immediately rather than failing later
-# inside a worker.
-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
-hr
-puts "Example 29 complete."