robot_lab 0.2.1 → 0.2.7

data/examples/24_structured_delegation.rb

@@ -18,7 +18,7 @@
 #   - Contrast with bus messaging (fire-and-forget) and pipelines (predefined)
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/24_structured_delegation.rb
+#   ruby examples/24_structured_delegation.rb
 
 require_relative "common"
 
@@ -28,19 +28,19 @@ banner "Structured Delegation"
 # Build a manager and two specialist robots
 # ---------------------------------------------------------------------------
 manager = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name:          "manager",
   system_prompt: "You are a project manager. Delegate tasks concisely."
 )
 
 summarizer = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name:          "summarizer",
   system_prompt: "You are a concise summarizer. Produce a 1-2 sentence summary."
 )
 
 analyst = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name:          "analyst",
   system_prompt: "You are a data analyst. Identify the key metric in one sentence."
 )
@@ -89,12 +89,12 @@ section "Asynchronous (parallel fan-out)"
 
 # Fresh robots — each delegate call should start from a clean slate
 async_summarizer = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name:          "summarizer",
   system_prompt: "You are a concise summarizer. Produce a 1-2 sentence summary."
 )
 async_analyst = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name:          "analyst",
   system_prompt: "You are a data analyst. Identify the key metric in one sentence."
 )
@@ -109,8 +109,13 @@ puts "Both futures launched. Futures resolved? " \
      "summary=#{f_summary.resolved?} analysis=#{f_analysis.resolved?}"
 puts "Collecting results..."
 
-summary  = f_summary.value(timeout: 60)
-analysis = f_analysis.value(timeout: 60)
+# value(timeout:) raises DelegationFuture::DelegationTimeout if the delegatee
+# hasn't finished in time. A local model is much slower than a hosted one, so
+# budget generously — 60s is comfortably too short for a 20B+ model.
+DELEGATION_TIMEOUT = Integer(ENV.fetch("DELEGATION_TIMEOUT", "600"))
+
+summary  = f_summary.value(timeout: DELEGATION_TIMEOUT)
+analysis = f_analysis.value(timeout: DELEGATION_TIMEOUT)
 
 elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
 

data/examples/25_history_search.rb

@@ -23,17 +23,21 @@ CONVERSATION_TURNS = File.readlines(
 banner "Chat History Search"
 
 # ---------------------------------------------------------------------------
-# Minimal message stub — populates history without LLM calls
+# Build a robot and load the conversation fixture
+#
+# Robot#replace_messages is the supported way to install a saved conversation
+# — checkpoint restore, replaying a transcript, or seeding a fixture like this
+# one. It resets the chat and re-adds each message, so there is no need to
+# reach into @chat and overwrite @messages by hand.
 # ---------------------------------------------------------------------------
-FakeMsg = Struct.new(:role, :content, :tool_calls)
+robot = RobotLab.build(**llm_opts, name: "tech_lead", system_prompt: "You are a senior engineering advisor.")
 
-# ---------------------------------------------------------------------------
-# Build a robot and inject the conversation fixture
-# ---------------------------------------------------------------------------
-robot = RobotLab.build(model: LLM[:default].model, name: "tech_lead", system_prompt: "You are a senior engineering advisor.")
+messages = CONVERSATION_TURNS.map do |turn|
+  RubyLLM::Message.new(role: turn[:role].to_sym, content: turn[:content])
+end
+robot.replace_messages(messages)
 
-messages = CONVERSATION_TURNS.map { |t| FakeMsg.new(t[:role], t[:content], nil) }
-robot.instance_variable_get(:@chat).instance_variable_set(:@messages, messages)
+messages = robot.messages
 
 total_words = messages.sum { |m| m.content.to_s.split.size }
 puts "Conversation loaded: #{messages.size} messages, ~#{total_words} words"

data/examples/27_incident_response/incident_response.rb

@@ -60,7 +60,7 @@ class SREScout < RobotLab::Robot
   def initialize(name:, subsystem:, memory_key:, bus: nil)
     super(
       name: name,
-      model: LLM[:default].model,
+      **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.",
@@ -111,9 +111,8 @@ class WarRoom < RobotLab::Robot
   attr_reader :updates
 
   def initialize(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
+    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.
@@ -137,15 +136,12 @@ end
 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 = @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
+    findings = collect_findings
 
     prompt = <<~PROMPT
       Three SRE scouts have reported their findings for a payment-service outage.
@@ -167,6 +163,24 @@ class IncidentCommander < RobotLab::Robot
 
     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 ────────────────────────────────────────────────────────────────
@@ -177,7 +191,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", model: LLM[:default].model, system_prompt: "SRE incident commander.")
+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.
@@ -212,8 +226,12 @@ puts
 puts network.visualize
 puts
 
-puts "Poller groups registered on network BusPoller:"
-puts "  #{network.instance_variable_get(:@bus_poller).groups.inspect}"
+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"

data/examples/28_mcp_discovery.rb

@@ -12,7 +12,7 @@
 # == Key config
 #
 #   robot = RobotLab.build(
-#     model: "gpt-5.4",
+#     provider: "ollama", model: "qwen3.6:latest",
 #     mcp_discovery: true,    # ← enables semantic filtering
 #     mcp: [ ... ]            # ← candidate servers, each with :description
 #   )
@@ -55,8 +55,9 @@ 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 "  #{label}"
+  puts "    Query : #{query.inspect}"
+  puts "    Match : #{names.inspect}"
   puts
 end
 
@@ -91,19 +92,22 @@ puts "  High threshold  : returns all (#{result.size} servers) — no match abov
 
 puts
 section "mcp_discovery: true on a Robot"
-puts <<~NOTE
-  RobotLab.build(
-  model: "gpt-5.4",
-    name: "assistant",
+show_code <<~RUBY
+  robot = RobotLab.build(
+    name:          "assistant",
+    provider:      "ollama",
+    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: { ... } }
+      { 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
+  # 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

@@ -16,7 +16,7 @@
 #   - ToolError         — propagated when a tool raises inside a Ractor
 #   - Parallel batch    — many threads submitting concurrently vs sequentially
 #
-# Usage (no LLM API key required):
+# Usage (no LLM traffic — pure CPU work):
 #   bundle exec ruby examples/29_ractor_tools.rb
 #
 # Good to know:
@@ -157,7 +157,9 @@ 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.
+# 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"))

data/examples/30_ractor_network.rb

@@ -15,20 +15,20 @@
 #   - RactorNetworkScheduler              — direct use for testing / custom wiring
 #   - Result Hash                         — run_pipeline returns { name => result }
 #
-# Part 1 — simulated scheduler, no API key needed.
+# Part 1 — simulated scheduler, no LLM traffic.
 #   Overrides execute_spec with a sleep-based stub so the wave ordering and
 #   timing characteristics are visible without real LLM calls.
 #
 # Part 2 — Network.new(parallel_mode: :ractor) API walkthrough.
 #   Shows how to configure the network and inspects the dependency graph.
-#   No run() call is made, so no API key is required.
+#   No run() call is made, so no LLM traffic either.
 #
-# Part 3 — live LLM run (optional).
-#   Executes automatically when ANTHROPIC_API_KEY is set.
+# Part 3 — live LLM run (opt-in via RUN_LIVE).
+#   Expected to fail against ruby_llm today; the rescue clauses explain why.
 #
 # Usage:
-#   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
+#   bundle exec ruby examples/30_ractor_network.rb            # Parts 1 & 2
+#   RUN_LIVE=1 bundle exec ruby examples/30_ractor_network.rb # Parts 1, 2 & 3
 
 require_relative "common"
 require "robot_lab/ractor"
@@ -69,7 +69,7 @@ LATENCIES = {
 #
 #   Speedup    ≈ 1.7×
 
-section "Part 1: Simulated Parallel Run (no API key)"
+section "Part 1: Simulated Parallel Run (no LLM traffic)"
 
 # SimulatedScheduler overrides execute_spec so that instead of
 # constructing a real Robot and calling the LLM, it just sleeps for
@@ -141,27 +141,25 @@ section "Part 2: Network.new(parallel_mode: :ractor)"
 # routes through RactorNetworkScheduler instead of SimpleFlow::Pipeline.
 # The default mode is :async (unchanged SimpleFlow behavior).
 
-model = LLM[:default].model
-
 network = RobotLab::Network.new(name: "research_pipeline", parallel_mode: :ractor) do
   task :headline_finder,  RobotLab.build(name: "headline_finder",
                                           system_prompt: "Find the 3 most relevant news headlines. Be concise.",
-                                          model: model),
+                                          **llm_opts),
        depends_on: :none
 
   task :background_brief, RobotLab.build(name: "background_brief",
                                           system_prompt: "Provide a 2-sentence background on the topic.",
-                                          model: model),
+                                          **llm_opts),
        depends_on: :none
 
   task :fact_checker,     RobotLab.build(name: "fact_checker",
                                           system_prompt: "List 3 verifiable facts about the topic.",
-                                          model: model),
+                                          **llm_opts),
        depends_on: :none
 
   task :report_writer,    RobotLab.build(name: "report_writer",
                                           system_prompt: "Synthesize the provided context into a 3-sentence report.",
-                                          model: model),
+                                          **llm_opts),
        depends_on: ["headline_finder", "background_brief", "fact_checker"]
 end
 
@@ -187,21 +185,28 @@ puts "    • Return value is a Hash { robot_name => result_string }"
 puts
 
 # =============================================================================
-# Part 3: Live LLM run (optional — requires ANTHROPIC_API_KEY)
+# Part 3: Live LLM run (opt-in via RUN_LIVE=1)
 # =============================================================================
 
-unless ENV["ANTHROPIC_API_KEY"]
+unless ENV["RUN_LIVE"]
   section "Part 3: Live LLM Run"
-  puts "   Set ANTHROPIC_API_KEY to run the real pipeline."
+  puts "   Set RUN_LIVE=1 (with Ollama running) to attempt the real pipeline."
   puts "   Expected behavior: headline_finder, background_brief, and"
   puts "   fact_checker run in parallel; report_writer follows."
   puts
+  puts "   Heads-up: this is expected to fail today — see the rescue clauses"
+  puts "   below. ruby_llm keeps Procs in class-level state, which cannot"
+  puts "   cross a Ractor boundary. Part 1 shows the wave ordering that Part 3"
+  puts "   will exercise once ruby_llm is Ractor-safe."
+  puts
   hr
   puts "Example 30 complete."
   exit 0
 end
 
-section "Part 3: Live LLM Run (ANTHROPIC_API_KEY detected)"
+require_ollama!
+
+section "Part 3: Live LLM Run (RUN_LIVE set)"
 
 puts "  Running 4-robot research pipeline on:"
 puts "  \"#{topic}\""

data/examples/31_launch_assessment.rb

@@ -45,7 +45,7 @@
 #   RunConfig.new(max_concurrent_robots: 4)
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/31_launch_assessment.rb
+#   ruby examples/31_launch_assessment.rb
 
 require_relative "common"
 
@@ -61,7 +61,7 @@ class AnalystRobot < RobotLab::Robot
   def initialize(name:, memory_key:, role:)
     super(
       name:          name,
-      model:         LLM[:default].model,
+      **llm_opts,
       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."
@@ -111,12 +111,7 @@ class LaunchDirector < RobotLab::Robot
 
   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
+    findings = collect_findings
 
     prompt = <<~PROMPT
       Six specialist analysts have reviewed our product launch readiness.
@@ -139,6 +134,22 @@ class LaunchDirector < RobotLab::Robot
 
     result.with_context(:recommendation, recommendation).continue(recommendation)
   end
+
+  private
+
+  # Memory#get(wait:) RAISES RobotLab::AwaitTimeout on expiry — it never
+  # returns a :timeout sentinel. Rescue it and re-read without wait:, which
+  # never blocks and omits keys that were never written, so a stalled analyst
+  # degrades the recommendation instead of killing the director.
+  def collect_findings
+    @shared_memory.get(*FINDING_KEYS, wait: 120)
+  rescue RobotLab::AwaitTimeout => e
+    puts "  [#{name}] WARNING: #{e.message}"
+    partial = @shared_memory.get(*FINDING_KEYS)
+    missing = FINDING_KEYS - partial.keys
+    puts "  [#{name}] Proceeding without: #{missing.join(', ')}" if missing.any?
+    partial
+  end
 end
 
 # ── Product Brief ───────────────────────────────────────────────────────────────
@@ -169,7 +180,7 @@ end
 
 director = LaunchDirector.new(
   name:          "launch_director",
-  model:         LLM[:default].model,
+  **llm_opts,
   system_prompt: "You are the VP of Product making the final launch call."
 )
 

data/examples/32_newsletter_reader.rb

@@ -3,8 +3,12 @@
 
 # Example 32: Newsletter Issue Retriever
 #
+# NOTE: this is a plain utility script, not a RobotLab demo — it uses no part
+# of the library. It lives here as the content feeder for other experiments.
+# Read examples 01-31 for library capabilities.
+#
 # Fetches all unprocessed issues from multiple Ruby newsletters via RSS
-# and saves each as a Markdown file in the Obsidian Clippings folder.
+# and saves each as a Markdown file in a Markdown clippings folder.
 #
 # - Processes oldest unprocessed issue first (across all feeds)
 # - Filename: <newsletter-name>_YYYYMMDD.md
@@ -13,6 +17,7 @@
 #
 # Usage:
 #   ruby examples/32_newsletter_reader.rb
+#   CLIPPINGS_DIR=~/Notes/Clippings ruby examples/32_newsletter_reader.rb
 
 require "net/http"
 require "open3"
@@ -28,7 +33,7 @@ NEWSLETTER_RSS_URLS = [
   "https://cprss.s3.amazonaws.com/rubyweekly.com.xml"   # Ruby Weekly
 ].freeze
 
-CLIPPINGS_DIR        = File.expand_path("/Users/dewayne/Documents/obsidian_order_intelligence/PKM/Clippings")
+CLIPPINGS_DIR        = File.expand_path(ENV.fetch("CLIPPINGS_DIR", "~/Documents/Clippings"))
 PROCESSED_STATE_FILE = File.join(Dir.home, ".robot_lab", "newsletter_processed.yaml")
 
 # Tracks which newsletter issue URLs have been saved.

data/examples/33_stock_predictor.rb

@@ -14,12 +14,12 @@
 # Prerequisites:
 #   gem install redis
 #   Redis server running on localhost:6379
+#   Ollama running with the model from common.rb pulled
 #
 # Usage:
 #   ruby examples/33_stock_predictor.rb
 
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "robot_lab"
+require_relative "common"
 require "robot_lab/durable"
 require "redis"
 require "json"
@@ -204,12 +204,15 @@ 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,
+require_ollama!
+
+redis  = Redis.new
+prices = []
+
+robot = RobotLab.build(
+  **llm_opts,
+  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.
@@ -231,10 +234,21 @@ robot      = RobotLab.build(
                    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"
-             )
+  local_tools:   [AdjustParameters]
+)
+
+# Durable learning is enabled AFTER construction. Robot#initialize takes a
+# fixed keyword list with no **rest, so `learn:`/`learn_domain:` constructor
+# params raise ArgumentError; the Durable::Learning mixin exposes
+# setup_durable_learning instead. It seeds @learnings from
+# ~/.robot_lab/durable/<domain>.yml and appends the RecallKnowledge and
+# RecordKnowledge tools to local_tools.
+robot.setup_durable_learning(domain: "xyzzy stock prediction")
+
+puts "Durable domain : xyzzy stock prediction"
+puts "Tools          : #{robot.local_tools.map(&:name).join(', ')}"
+puts "Seeded learnings: #{robot.learnings.size}"
+puts "-" * 60
 
 warmed_up    = false
 pending_pred = nil  # { prediction: {high:, low:}, window_prices: [] }
@@ -291,10 +305,17 @@ redis.subscribe(CHANNEL) do |on|
     puts "#{"─" * 60}"
 
     print "  [tuner] analyzing window #{window_num}..."
-    tuner_response = robot.run(tuner_prompt(result))
+    # tools: :inherit is required — run() defaults to :none, which sends the
+    # provider an empty tool list, so AdjustParameters/RecallKnowledge/
+    # RecordKnowledge would never be callable.
+    tuner_response = robot.run(tuner_prompt(result), tools: :inherit)
     tuner_line     = tuner_response.reply.lines.first&.chomp || "(no response)"
     puts "\r  [tuner] #{tuner_line}#{" " * 20}"
     puts "  Params: #{PredictorConfig.summary}"
+
+    # Promote this session's learnings into the durable YAML store. Core
+    # Robot#run does not invoke the reflector, so the caller drives it.
+    robot.run_reflector
     puts
 
     # ── Start next window ──────────────────────────────────────────

data/examples/34_agentskills.rb

@@ -10,9 +10,10 @@
 # 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
+#   ruby examples/34_agentskills.rb
 
 require_relative "common"
+require "robot_lab/document_store"
 
 require "logger"
 log_file = File.join(__dir__, "34.log")
@@ -36,13 +37,16 @@ end
 # "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,
+  **llm_opts,
   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 "Declared skills: #{robot.skills.inspect}"
+puts "(Folder-format skills are matched per-run by embedding similarity, so"
+puts " whether one is injected depends on the message — watch the two queries"
+puts " below.)"
 puts
 
 # Message semantically related to code review — skill should activate