robot_lab 0.0.12 → 0.2.1

data/examples/25_history_search.rb

@@ -13,19 +13,14 @@
 # Usage:
 #   ruby examples/25_history_search.rb
 
-ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
-
 require "json"
-require_relative "../lib/robot_lab"
+require_relative "common"
 
 CONVERSATION_TURNS = File.readlines(
   File.join(__dir__, "25_history_search", "conversation.jsonl"), chomp: true
 ).map { |line| JSON.parse(line, symbolize_names: true) }.freeze
 
-puts "=" * 60
-puts "Example 25: Chat History Search"
-puts "=" * 60
-puts
+banner "Chat History Search"
 
 # ---------------------------------------------------------------------------
 # Minimal message stub — populates history without LLM calls
@@ -35,7 +30,7 @@ FakeMsg = Struct.new(:role, :content, :tool_calls)
 # ---------------------------------------------------------------------------
 # Build a robot and inject the conversation fixture
 # ---------------------------------------------------------------------------
-robot = RobotLab.build(name: "tech_lead", system_prompt: "You are a senior engineering advisor.")
+robot = RobotLab.build(model: LLM[:default].model, name: "tech_lead", system_prompt: "You are a senior engineering advisor.")
 
 messages = CONVERSATION_TURNS.map { |t| FakeMsg.new(t[:role], t[:content], nil) }
 robot.instance_variable_get(:@chat).instance_variable_set(:@messages, messages)
@@ -88,7 +83,7 @@ end
 # ---------------------------------------------------------------------------
 # RAG pattern — retrieve the most relevant turns, then inject as context
 # ---------------------------------------------------------------------------
-puts "── RAG pattern: retrieve context, then call LLM ────────────────"
+section "RAG Pattern: Retrieve Context, Then Call LLM"
 puts "(showing retrieved context — no actual LLM call)"
 puts
 
@@ -111,9 +106,7 @@ puts
 # ---------------------------------------------------------------------------
 # When to use search_history
 # ---------------------------------------------------------------------------
-puts "=" * 60
-puts "When to use search_history"
-puts "=" * 60
+section "When to Use search_history"
 puts <<~'TEXT'
 
   Without search_history:

data/examples/26_document_store.rb

@@ -13,14 +13,10 @@
 #   ruby examples/26_document_store.rb
 #   (Downloads the ~23 MB ONNX model on first run; cached afterwards.)
 
-ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+require_relative "common"
+require "robot_lab/document_store"
 
-require_relative "../lib/robot_lab"
-
-puts "=" * 60
-puts "Example 26: Embedding-Based Document Store"
-puts "=" * 60
-puts
+banner "Embedding-Based Document Store"
 puts "Note: First run downloads the fastembed model (~23 MB, cached)."
 puts
 
@@ -97,7 +93,7 @@ end
 # ---------------------------------------------------------------------------
 # Delete and verify
 # ---------------------------------------------------------------------------
-puts "── Delete :redis_caching_guide, re-run cache query"
+section "Delete :redis_caching_guide, Re-run Cache Query"
 store.delete(:redis_caching_guide)
 results = store.search("Redis evicting keys unexpectedly", limit: 2)
 puts "   Remaining keys: #{store.keys.inspect}"
@@ -107,7 +103,7 @@ puts
 # ---------------------------------------------------------------------------
 # Memory integration
 # ---------------------------------------------------------------------------
-puts "── Memory integration"
+section "Memory Integration"
 memory = RobotLab::Memory.new(enable_cache: false)
 
 DOCUMENTS.each { |key, text| memory.store_document(key, text) }
@@ -124,10 +120,7 @@ puts
 # ---------------------------------------------------------------------------
 # RAG pattern
 # ---------------------------------------------------------------------------
-puts "=" * 60
-puts "RAG Pattern: retrieve relevant docs, then generate with LLM"
-puts "=" * 60
-puts
+section "RAG Pattern: Retrieve Relevant Docs, Then Generate with LLM"
 
 rag_query = "Our Sidekiq jobs exhaust retries and land in the dead queue after a Stripe outage."
 

data/examples/27_incident_response/incident_response.rb

@@ -38,11 +38,9 @@
 
 ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "../prompts")
 
-require_relative "../../lib/robot_lab"
+require_relative "../common"
 require "fileutils"
 
-RubyLLM.configure { |c| c.logger = Logger.new(File::NULL) }
-
 OUTPUT_DIR = File.join(__dir__, "output")
 FileUtils.mkdir_p(OUTPUT_DIR)
 
@@ -62,6 +60,7 @@ class SREScout < RobotLab::Robot
   def initialize(name:, subsystem:, memory_key:, bus: nil)
     super(
       name: name,
+      model: LLM[:default].model,
       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.",
@@ -112,7 +111,7 @@ class WarRoom < RobotLab::Robot
   attr_reader :updates
 
   def initialize(bus:)
-    super(name: "war_room", system_prompt: "SRE war-room coordinator.", bus: bus)
+    super(name: "war_room", model: LLM[:default].model, system_prompt: "SRE war-room coordinator.", bus: bus)
     @updates        = []
     @delivery_mutex = Mutex.new  # only for reading @updates outside Async
 
@@ -178,7 +177,7 @@ db_scout  = SREScout.new(name: "db_scout",  subsystem: "database",    memory_key
 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.")
+commander = IncidentCommander.new(name: "commander", model: LLM[:default].model, system_prompt: "SRE incident commander.")
 
 # Build the investigation network
 # poller_group: labels are registered on the network's shared BusPoller.

data/examples/28_mcp_discovery.rb

@@ -12,6 +12,7 @@
 # == Key config
 #
 #   robot = RobotLab.build(
+#     model: "gpt-5.4",
 #     mcp_discovery: true,    # ← enables semantic filtering
 #     mcp: [ ... ]            # ← candidate servers, each with :description
 #   )
@@ -29,7 +30,7 @@
 # Usage:
 #   bundle exec ruby examples/28_mcp_discovery.rb
 
-require_relative "../lib/robot_lab"
+require_relative "common"
 
 # Three representative MCP server configurations
 SERVERS = [
@@ -59,10 +60,8 @@ def show_query(label, query)
   puts
 end
 
-puts "=" * 60
-puts "Example 28: MCP Server Discovery"
+banner "MCP Server Discovery"
 puts "  Semantic server selection via TF cosine similarity"
-puts "=" * 60
 puts
 puts "Candidate servers:"
 SERVERS.each do |s|
@@ -70,14 +69,12 @@ SERVERS.each do |s|
 end
 puts
 
-puts "Discovery queries:"
-puts "-" * 60
+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")
 
-puts "Fallback cases:"
-puts "-" * 60
+section "Fallback Cases"
 
 # No description → all servers returned
 no_desc_servers = SERVERS.map { |s| s.except(:description) }
@@ -93,10 +90,10 @@ result = RobotLab::MCP::ServerDiscovery.select("install imagemagick", from: SERV
 puts "  High threshold  : returns all (#{result.size} servers) — no match above 1.0"
 
 puts
-puts "mcp_discovery: true on a Robot"
-puts "-" * 60
+section "mcp_discovery: true on a Robot"
 puts <<~NOTE
   RobotLab.build(
+  model: "gpt-5.4",
     name: "assistant",
     mcp_discovery: true,
     mcp: [
@@ -109,4 +106,4 @@ puts <<~NOTE
   # Only the :brew server is connected for this message:
   robot.run("install imagemagick")
 NOTE
-puts "=" * 60
+hr

data/examples/29_ractor_tools.rb

@@ -26,9 +26,8 @@
 #   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_relative "common"
+require "robot_lab/ractor"
 require "digest"
 
 # Always shut down the pool when the process exits.
@@ -115,10 +114,7 @@ end
 # Demo
 # =============================================================================
 
-puts "=" * 62
-puts "Example 29: Ractor-Safe CPU Tools"
-puts "=" * 62
-puts
+banner "Ractor-Safe CPU Tools"
 
 DIVIDER = ("─" * 54).freeze
 
@@ -238,6 +234,5 @@ puts "    #{DIVIDER}"
 RobotLab.shutdown_ractor_pool
 puts "    Pool shut down cleanly (poison-pill × #{pool.size} workers)."
 puts
-puts "=" * 62
+hr
 puts "Example 29 complete."
-puts "=" * 62

data/examples/30_ractor_network.rb

@@ -30,14 +30,10 @@
 #   bundle exec ruby examples/30_ractor_network.rb              # Parts 1 & 2
 #   ANTHROPIC_API_KEY=key ruby examples/30_ractor_network.rb    # Parts 1, 2 & 3
 
-ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+require_relative "common"
+require "robot_lab/ractor"
 
-require_relative "../lib/robot_lab"
-
-puts "=" * 62
-puts "Example 30: Ractor Network Scheduler"
-puts "=" * 62
-puts
+banner "Ractor Network Scheduler"
 
 DIVIDER = ("─" * 54).freeze
 
@@ -73,8 +69,7 @@ LATENCIES = {
 #
 #   Speedup    ≈ 1.7×
 
-puts "── Part 1: Simulated parallel run (no API key) ───────────"
-puts
+section "Part 1: Simulated Parallel Run (no API key)"
 
 # SimulatedScheduler overrides execute_spec so that instead of
 # constructing a real Robot and calling the LLM, it just sleeps for
@@ -140,14 +135,13 @@ puts
 # Part 2: Network.new(parallel_mode: :ractor) API
 # =============================================================================
 
-puts "── Part 2: Network.new(parallel_mode: :ractor) ───────────"
-puts
+section "Part 2: Network.new(parallel_mode: :ractor)"
 
 # When parallel_mode: :ractor is set on a Network, network.run(message:)
 # routes through RactorNetworkScheduler instead of SimpleFlow::Pipeline.
 # The default mode is :async (unchanged SimpleFlow behavior).
 
-model = "claude-haiku-4-5-20251001"
+model = LLM[:default].model
 
 network = RobotLab::Network.new(name: "research_pipeline", parallel_mode: :ractor) do
   task :headline_finder,  RobotLab.build(name: "headline_finder",
@@ -197,19 +191,17 @@ puts
 # =============================================================================
 
 unless ENV["ANTHROPIC_API_KEY"]
-  puts "── Part 3: Live LLM run ──────────────────────────────────"
+  section "Part 3: Live LLM Run"
   puts "   Set ANTHROPIC_API_KEY to run the real pipeline."
   puts "   Expected behavior: headline_finder, background_brief, and"
   puts "   fact_checker run in parallel; report_writer follows."
   puts
-  puts "=" * 62
+  hr
   puts "Example 30 complete."
-  puts "=" * 62
   exit 0
 end
 
-puts "── Part 3: Live LLM run (ANTHROPIC_API_KEY detected) ─────"
-puts
+section "Part 3: Live LLM Run (ANTHROPIC_API_KEY detected)"
 
 puts "  Running 4-robot research pipeline on:"
 puts "  \"#{topic}\""
@@ -251,6 +243,5 @@ rescue RobotLab::Error => e
 end
 
 puts
-puts "=" * 62
+hr
 puts "Example 30 complete."
-puts "=" * 62

data/examples/31_launch_assessment.rb

@@ -0,0 +1,235 @@
+#!/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
+
+require_relative "common"
+
+# ── 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,
+      model:         LLM[:default].model,
+      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",
+  model:         LLM[:default].model,
+  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 ─────────────────────────────────────────────────────────────────────────
+
+banner "Product Launch Assessment"
+puts "  6 specialist analysts in parallel, max_concurrent_robots: 4"
+puts
+puts "Pipeline:"
+puts network.visualize
+puts
+puts "Concurrency config: #{config.inspect}"
+puts
+puts "Product brief:"
+puts PRODUCT_BRIEF.strip.gsub(/^/, "  ")
+puts
+section "Running — Analysts 5 and 6 Queue Until a Semaphore Slot Opens"
+
+$run_start = Time.now
+result     = network.run(message: PRODUCT_BRIEF)
+elapsed    = "%.1f" % (Time.now - $run_start)
+
+puts
+hr
+puts "All analysts complete. Total wall time: #{elapsed}s"
+hr
+
+section "Launch Director Recommendation"
+puts network.memory[:recommendation]
+puts
+section "Individual Analyst Verdicts"
+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