robot_lab 0.2.1 → 0.2.7

data/examples/16_writers_room/writer.rb

@@ -20,13 +20,15 @@
 # In a bus-based SOG, writers receive many messages and each
 # triggers a run() call. When the LLM responds with only tool
 # calls (no text), RubyLLM appends an empty text content block
-# to the chat history. The Anthropic API rejects this on the
-# next call, permanently killing the writer.
+# to the chat history. Several providers reject that on the next
+# call, permanently killing the writer.
 #
-# Fix: reset the chat before each message. The writer doesn't
-# need persistent chat history — shared memory is the single
-# source of truth. Each message is processed with a fresh chat
-# that has the system prompt, tools, and current memory context.
+# Fix: reset the conversation before each message via the public
+# Robot#clear_messages(keep_system: true). The writer doesn't need
+# persistent chat history — shared memory is the single source of
+# truth. Rebuilding @chat by hand instead would drop the tool
+# callbacks and chat params that Robot#initialize installed, so
+# clear_messages is both shorter and safer.
 #
 class Writer < RobotLab::Robot
   attr_accessor :shared_memory, :display, :room
@@ -40,6 +42,7 @@ class Writer < RobotLab::Robot
 
     super(
       name:        name,
+      **llm_opts,
       template:    room.mode[:template],
       context:     { writer_name: name },
       bus:         bus,
@@ -69,24 +72,18 @@ class Writer < RobotLab::Robot
     ]
   end
 
+  # Room deliveries go to this robot's BusPoller, which serializes them
+  # behind any run() already in flight before invoking on_message.
   def setup_room_subscription
     @bus.subscribe(:room) do |delivery|
-      handle_incoming_delivery(delivery)
+      enqueue_delivery(delivery)
     end
   end
 
-  # Reset the chat to a clean state with system prompt and tools.
-  # Prevents history corruption from tool-only LLM responses
-  # (empty text content blocks that Anthropic rejects).
-  def fresh_chat!
-    resolved_model = @config&.model || RobotLab.config.ruby_llm.model
-    @chat = RubyLLM.chat(model: resolved_model)
-    apply_template_to_chat(@build_context) if @template
-    @chat.with_instructions(@system_prompt) if @system_prompt
-    @chat.with_temperature(@config.temperature) if @config&.temperature
-
-    filtered = filtered_tools([])
-    @chat.with_tools(*filtered) if filtered.any?
+  # Drop the turn history, keep the rendered system prompt. Model,
+  # temperature, tools and the tool callbacks all survive untouched.
+  def reset_conversation!
+    clear_messages(keep_system: true)
   end
 
   def setup_message_handler
@@ -98,8 +95,8 @@ class Writer < RobotLab::Robot
       log&.info("#{name} <- [#{message.from}] msg ##{@messages_processed} (#{message.content.to_s[0..80]}...)")
       @display&.incoming(name, message.from, message.content)
 
-      # Fresh chat for each message — shared memory is our persistence
-      fresh_chat!
+      # Fresh conversation for each message — shared memory is our persistence
+      reset_conversation!
 
       # Build prompt with current memory context
       memory_keys = shared_memory.keys
@@ -109,7 +106,10 @@ class Writer < RobotLab::Robot
       log&.info("#{name} -> run() starting (prompt: #{prompt.length} chars)")
 
       begin
-        result = run(prompt)
+        # tools: :inherit — run() defaults to :none. Without it the writer
+        # would have all seven tools attached and none of them offered to the
+        # model, so nothing would ever be written to shared memory.
+        result = run(prompt, tools: :inherit)
         reply_text = result.respond_to?(:reply) ? result.reply.to_s[0..120] : result.to_s[0..120]
         log&.info("#{name} <- run() finished (reply: #{reply_text}...)")
       rescue => e

data/examples/16_writers_room/writers_room.rb

@@ -125,6 +125,8 @@ FileUtils.mkdir_p(OUTPUT_DIR)
 
 display = Display.new(log_path: log_path)
 
+# RunConfig has no `provider` field, so the writers get provider+model via
+# **llm_opts and inherit the rest of their operational defaults from here.
 shared_config = RobotLab::RunConfig.new(
   model: LLM[:default].model,
   temperature: 0.7

data/examples/17_skills.rb

@@ -29,7 +29,7 @@
 #   6. incident_responder   — "you are the on-call analyst for..."
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/17_skills.rb
+#   ruby examples/17_skills.rb
 #
 # Templates:
 #   examples/prompts/
@@ -136,7 +136,7 @@ puts
 # - sre_compliance:    Recursive skill — auto-expands to include pii_redactor
 #                      and audit_trail before its own compliance instructions
 responder = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "incident_responder",
   template: :incident_responder,
   skills: [:runbook_protocol, :structured_output, :sre_compliance],
@@ -147,17 +147,20 @@ responder = RobotLab.build(
   }
 )
 
-# Show what the robot got
+# Show what the robot got.
+#
+# `skills` is the DECLARED list. The expanded list (with sre_compliance's
+# nested skills spliced in ahead of it) has no public reader — but you don't
+# need one, because the expansion is visible in the assembled system prompt
+# printed below, which is the thing that actually reaches the model.
 puts "Robot: #{responder.name}"
-puts "Skills: #{responder.skills.inspect}"
-puts "Expanded skills: #{responder.instance_variable_get(:@expanded_skills).inspect}"
+puts "Declared skills: #{responder.skills.inspect}"
 puts "Model: #{responder.model}"
 puts
 
-# Display the assembled system prompt
-chat = responder.instance_variable_get(:@chat)
-messages = chat.instance_variable_get(:@messages)
-system_msg = messages.find { |m| m.role.to_s == "system" }
+# Display the assembled system prompt.
+# Robot#messages is a public reader over the chat's message list.
+system_msg = responder.messages.find { |m| m.role.to_s == "system" }
 if system_msg
   prompt = system_msg.content
   hr
@@ -174,7 +177,7 @@ end
 # =============================================================================
 
 plain_responder = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "plain_responder",
   template: :incident_responder,
   context: {
@@ -184,9 +187,7 @@ plain_responder = RobotLab.build(
   }
 )
 
-plain_chat = plain_responder.instance_variable_get(:@chat)
-plain_messages = plain_chat.instance_variable_get(:@messages)
-plain_msg = plain_messages.find { |m| m.role.to_s == "system" }
+plain_msg = plain_responder.messages.find { |m| m.role.to_s == "system" }
 if plain_msg
   puts
   puts "For comparison — plain responder (no skills): #{plain_msg.content.length} chars"

data/examples/18_rails/README.md

@@ -11,7 +11,15 @@ Minimal Rails 8 app that demonstrates RobotLab's full Rails integration:
 ## Prerequisites
 
 - Ruby 3.2+
-- An LLM API key (e.g. `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in your env)
+- [Ollama](https://ollama.com) running locally with the demo model pulled:
+
+  ```bash
+  ollama serve
+  ollama pull qwen3.6
+  ```
+
+No API keys. Override the model with `ROBOT_LAB_PROVIDER` / `ROBOT_LAB_MODEL`,
+and the endpoint with `OLLAMA_API_BASE`.
 
 ## Setup
 
@@ -33,6 +41,17 @@ bin/dev
 2. Refresh the page — conversation history is preserved
 3. Check `db/development.sqlite3` to see persisted threads and results
 
+## Two things worth copying
+
+**`RobotLab::RailsIntegration::Job` is the real superclass.** There is no
+`RobotLab::Job` alias, so `class RobotRunJob < RobotLab::Job` raises `NameError`
+at boot.
+
+**`tools: :inherit` has to reach `run`.** `Robot#run` defaults to `tools: :none`,
+which hands the provider an empty tool list. The job splats any extra keywords
+into `robot.run`, so the controller passes `tools: :inherit` at enqueue time —
+without it TimeTool is never offered and the model just guesses the time.
+
 ## Architecture
 
 ```

data/examples/18_rails/app/controllers/chat_controller.rb

@@ -24,10 +24,14 @@ class ChatController < ApplicationController
       checksum:        Digest::SHA256.hexdigest(message)
     )
 
+    # tools: :inherit is forwarded by the job straight through to robot.run.
+    # Without it run() defaults to tools: :none and TimeTool is never offered
+    # to the model, so "What time is it?" gets a guess instead of a tool call.
     RobotRunJob.perform_later(
       robot_class: "ChatRobot",
       message:     message,
-      thread_id:   thread_id
+      thread_id:   thread_id,
+      tools:       :inherit
     )
 
     respond_to do |format|

data/examples/18_rails/app/jobs/robot_run_job.rb

@@ -2,18 +2,24 @@
 
 # Generic background job for executing any robot asynchronously.
 #
-# Inherits from RobotLab::Job — Turbo Stream wiring, thread persistence,
-# and completion/error broadcasting are all handled by the base class.
+# Inherits from RobotLab::RailsIntegration::Job — Turbo Stream wiring, thread
+# persistence, and completion/error broadcasting are all handled by the base
+# class. (Note the full namespace: robot_lab-rails defines the class as
+# RobotLab::RailsIntegration::Job and registers no RobotLab::Job alias.)
 #
-# Pass robot_class: at enqueue time to select which robot to run.
+# Pass robot_class: at enqueue time to select which robot to run. Any extra
+# keywords are forwarded straight to robot.run — which is how `tools:` gets
+# through, since run defaults to :none and would otherwise send the model an
+# empty tool list.
 #
 # @example Enqueue from a controller
 #   RobotRunJob.perform_later(
 #     robot_class: "ChatRobot",
 #     message:     params[:message],
-#     thread_id:   session_id
+#     thread_id:   session_id,
+#     tools:       :inherit
 #   )
 #
-class RobotRunJob < RobotLab::Job
+class RobotRunJob < RobotLab::RailsIntegration::Job
   queue_as :default
 end

data/examples/18_rails/app/robots/chat_robot.rb

@@ -1,11 +1,22 @@
 # frozen_string_literal: true
 
+# Factory for the chat robot. RobotLab::RailsIntegration::Job calls
+# ChatRobot.build(on_content:, on_tool_call:) to wire Turbo streaming.
+#
+# The model is served locally by Ollama. Ollama models are absent from
+# RubyLLM's registry, so provider: must accompany model: — that is what makes
+# RubyLLM skip the registry lookup.
 class ChatRobot
   SYSTEM_PROMPT = "You are a friendly assistant. Be concise."
 
+  PROVIDER = ENV.fetch("ROBOT_LAB_PROVIDER", "ollama")
+  MODEL    = ENV.fetch("ROBOT_LAB_MODEL", "qwen3.6:latest")
+
   def self.build(**options)
     RobotLab.build(
       name: "chat",
+      provider: PROVIDER,
+      model: MODEL,
       system_prompt: SYSTEM_PROMPT,
       local_tools: [TimeTool],
       **options

data/examples/18_rails/config/initializers/robot_lab.rb

@@ -1,3 +1,11 @@
 # frozen_string_literal: true
 
 RobotLab.config.logger = Rails.logger
+
+# Runs against a local Ollama server — no API keys required.
+#   ollama serve
+#   ollama pull qwen3.6
+RubyLLM.configure do |c|
+  c.logger          = Rails.logger
+  c.ollama_api_base = ENV.fetch("OLLAMA_API_BASE", "http://localhost:11434/v1")
+end

data/examples/19_token_tracking.rb

@@ -14,24 +14,30 @@
 #   naturally increase as conversation context accumulates.
 #   Use a fresh robot.build when you need a genuinely fresh context.
 #
-# Anthropic and OpenAI both return token counts in every response.
-# Token counts are zero for providers that don't report usage data.
+# Ollama reports usage counts like the hosted providers do, so the tracking
+# API behaves identically — only the price per token differs. Token counts are
+# zero for providers that don't report usage data.
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/19_token_tracking.rb
+#   ruby examples/19_token_tracking.rb
 
 require_relative "common"
 
-# Anthropic claude-haiku-4-5 pricing (as of early 2026)
-HAIKU_INPUT_CPM  = 0.80   # $ per 1M input tokens
-HAIKU_OUTPUT_CPM = 4.00   # $ per 1M output tokens
+# Cost model. A local Ollama model bills nothing, so the interesting number is
+# what the same traffic WOULD have cost on a hosted model — set RATE_INPUT_CPM
+# and RATE_OUTPUT_CPM to your provider's $-per-1M-token rates to see it.
+# Defaults are zero: local inference is free.
+RATE_INPUT_CPM  = ENV.fetch("RATE_INPUT_CPM",  "0").to_f
+RATE_OUTPUT_CPM = ENV.fetch("RATE_OUTPUT_CPM", "0").to_f
 
 def token_summary(input, output)
   "in=#{input}  out=#{output}  total=#{input + output}"
 end
 
 def run_cost(input, output)
-  dollars = (input * HAIKU_INPUT_CPM + output * HAIKU_OUTPUT_CPM) / 1_000_000.0
+  return "$0.00000 (local)" if RATE_INPUT_CPM.zero? && RATE_OUTPUT_CPM.zero?
+
+  dollars = (input * RATE_INPUT_CPM + output * RATE_OUTPUT_CPM) / 1_000_000.0
   "$#{"%.5f" % dollars}"
 end
 
@@ -41,8 +47,18 @@ end
 
 banner "Per-Robot Token & Cost Tracking"
 
+puts "Model: #{LLM[:default].provider}/#{LLM[:default].model}"
+if RATE_INPUT_CPM.zero? && RATE_OUTPUT_CPM.zero?
+  puts "Rates: none set — local inference is free."
+  puts "       Set RATE_INPUT_CPM / RATE_OUTPUT_CPM to price the same traffic"
+  puts "       against a hosted provider."
+else
+  puts "Rates: $#{RATE_INPUT_CPM}/1M in, $#{RATE_OUTPUT_CPM}/1M out"
+end
+puts
+
 robot = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "analyst",
   system_prompt: "You are a concise technical analyst. Keep every reply under 40 words."
 )
@@ -106,7 +122,7 @@ puts "Fresh robot — genuinely zero context:"
 puts
 
 fresh = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "analyst2",
   system_prompt: "You are a concise technical analyst. Keep every reply under 40 words."
 )

data/examples/20_circuit_breaker.rb

@@ -12,7 +12,7 @@
 #
 # Key behaviour when the breaker fires:
 #   The chat history contains a dangling tool_use with no tool_result.
-#   Anthropic (and most providers) reject any subsequent request with that
+#   Most providers reject any subsequent request with that
 #   broken history.  You MUST call robot.clear_messages before reusing the
 #   same robot instance — or simply build a fresh robot.
 #
@@ -23,7 +23,7 @@
 #   - Contrast: robot without a circuit breaker on a task that terminates
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/20_circuit_breaker.rb
+#   ruby examples/20_circuit_breaker.rb
 
 require_relative "common"
 
@@ -69,14 +69,14 @@ TASK = "Run the batch process from step 1 using the MultiStepProcessor tool. " \
 # Part 1: Circuit breaker fires — rescue ToolLoopError, then recover
 #
 # After ToolLoopError the chat contains a dangling tool_use block with no
-# matching tool_result. Anthropic rejects any follow-up request with that
+# matching tool_result. Providers reject any follow-up request with that
 # history. Call clear_messages to flush the broken context before reuse.
 # -------------------------------------------------------------------------
 
 section "Part 1: Circuit Breaker Fires (max_tool_rounds: 5)"
 
 robot = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "process_runner",
   system_prompt: "You are a process runner. Execute tasks exactly as instructed.",
   local_tools: [MultiStepProcessor],
@@ -84,7 +84,10 @@ robot = RobotLab.build(
 )
 
 begin
-  robot.run(TASK)
+  # tools: :inherit — run() defaults to :none, which sends the provider an
+  # empty tool list. With no tool to loop on there would be nothing for the
+  # breaker to trip.
+  robot.run(TASK, tools: :inherit)
   puts "Process completed (unexpected for this demo)."
 rescue RobotLab::ToolLoopError => e
   puts "Circuit breaker fired!"
@@ -130,13 +133,13 @@ class SingleStep < RubyLLM::Tool
 end
 
 unguarded = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "calculator",
   system_prompt: "Use the provided tool to answer questions.",
   local_tools: [SingleStep]
 )
 
-result = unguarded.run("Double the number 21 using the tool.")
+result = unguarded.run("Double the number 21 using the tool.", tools: :inherit)
 puts "Result: #{result.reply&.strip}"
 puts
 

data/examples/21_learning_loop.rb

@@ -14,10 +14,12 @@
 #   - robot.learnings — read the accumulated list
 #   - Learnings injected as "LEARNINGS FROM PREVIOUS RUNS:" prefix
 #   - Superset dedup: a broader learning replaces narrower earlier ones
-#   - Memory persistence: learnings survive rebuilding with the same Memory
+#   - robot.memory[:learnings] — where the list is actually stored
+#   - Scope: learnings are per-robot and in-process; see robot_lab-durable
+#     (and example 33) for cross-session persistence
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/21_learning_loop.rb
+#   ruby examples/21_learning_loop.rb
 
 require_relative "common"
 
@@ -67,7 +69,7 @@ SNIPPETS = [
 banner "Learning Accumulation Loop"
 
 robot = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "code_reviewer",
   system_prompt: <<~PROMPT
     You are a concise Ruby code reviewer. For each snippet:
@@ -120,7 +122,7 @@ puts
 # Demonstrate superset dedup: a broader learning replaces narrower ones
 # ---------------------------------------------------------------
 section "Deduplication Demo"
-robot2 = RobotLab.build(name: "reviewer2", system_prompt: "You review code.")
+robot2 = RobotLab.build(**llm_opts, name: "reviewer2", system_prompt: "You review code.")
 
 robot2.learn("avoid using puts")
 robot2.learn("avoid using puts and p in production code")  # covers the first
@@ -130,26 +132,50 @@ robot2.learnings.each_with_index { |l, i| puts "  #{i + 1}. #{l}" }
 puts
 
 # ---------------------------------------------------------------
-# Demonstrate persistence: learnings survive a robot rebuild using
-# the same Memory object
+# Where learnings actually live
+#
+# learn() writes through to the robot's own Memory under :learnings.
+# Memory is exposed by the public `memory` reader, so you can inspect
+# (or serialize) the list without touching instance variables.
 # ---------------------------------------------------------------
-section "Persistence Across Rebuild"
+section "Learnings Are Backed by Robot Memory"
+
+puts "robot.memory.get(:learnings):"
+Array(robot.memory.get(:learnings)).each_with_index { |l, i| puts "  #{i + 1}. #{l}" }
+puts
+puts "Same list as robot.learnings? #{robot.memory.get(:learnings) == robot.learnings}"
+puts
+
+# ---------------------------------------------------------------
+# Scope: learnings do NOT survive a rebuild
+#
+# Robot#initialize always constructs a fresh Memory and there is no
+# `memory:` constructor parameter, so a new robot — even with the same
+# name — starts with an empty learning list. learn() is a within-process
+# accumulator, not a persistence layer.
+# ---------------------------------------------------------------
+section "Scope: In-Process Only"
 
-shared_memory = robot.instance_variable_get(:@memory)
 rebuilt = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "code_reviewer",
   system_prompt: "You review code."
 )
-rebuilt.instance_variable_set(:@memory, shared_memory)
-
-# Trigger the memory restore path
-persisted = shared_memory.get(:learnings)
-rebuilt.instance_variable_set(:@learnings, Array(persisted))
 
-puts "Learnings on rebuilt robot (#{rebuilt.learnings.size}):"
-rebuilt.learnings.each_with_index { |l, i| puts "  #{i + 1}. #{l}" }
+puts "Learnings on a freshly built robot of the same name: #{rebuilt.learnings.size}"
+puts "(Robot#initialize builds a new Memory every time — nothing carries over.)"
 puts
+puts <<~PERSIST
+  To carry knowledge across processes, use the robot_lab-durable gem:
+
+    require "robot_lab/durable"
+    robot.setup_durable_learning(domain: "ruby code review")
+    # ... run the robot ...
+    robot.run_reflector   # promotes learnings to ~/.robot_lab/durable/<domain>.yml
+
+  On the next boot setup_durable_learning seeds robot.learnings from that
+  YAML store. See examples/33_stock_predictor.rb for a working loop.
+PERSIST
 
 hr
 puts "Learning loop demo complete."

data/examples/22_context_compression.rb

@@ -3,14 +3,18 @@
 
 # Example 22: Context Window Compression
 #
-# Demonstrates robot.compress_history() for reducing token usage in long
-# conversations. Old turns are scored against the recent context using
-# stemmed term-frequency cosine similarity. High-relevance turns are kept
-# verbatim; irrelevant turns are dropped; medium-relevance turns can be
-# summarized by a second robot.
+# Drives RobotLab::HistoryCompressor directly over a synthetic transcript, so
+# the keep/drop/summarize decisions are visible without spending any tokens.
+# Old turns are scored against the recent context using stemmed
+# term-frequency cosine similarity. High-relevance turns are kept verbatim;
+# irrelevant turns are dropped; medium-relevance turns can be summarized.
+#
+# Robot#compress_history is the same algorithm applied in place to a live
+# robot's chat — it constructs a HistoryCompressor over robot.messages and
+# replaces them with the result. The final section shows that call.
 #
 # Demonstrates:
-#   - robot.compress_history() — drop/keep/summarize old turns in-place
+#   - HistoryCompressor.new(messages:, ...).call — pure, testable core
 #   - recent_turns: N — last N user+assistant pairs always protected
 #   - keep_threshold: / drop_threshold: — tunable relevance bands
 #   - summarizer: — optional lambda(text) -> String for medium-relevance
@@ -20,7 +24,7 @@
 #   gem 'classifier', '~> 2.3'   # add to your Gemfile
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/22_context_compression.rb
+#   ruby examples/22_context_compression.rb   # no LLM calls
 
 require_relative "common"
 
@@ -47,23 +51,15 @@ end
 
 banner "Context Window Compression"
 
-# ---------------------------------------------------------------------------
-# Build a robot and simulate a long conversation on two topics
-# ---------------------------------------------------------------------------
-bot = RobotLab.build(
-  model: LLM[:default].model,
-  name:          "assistant",
-  system_prompt: "You are a concise Ruby expert. Reply in 2-3 sentences."
-)
-
-puts "Simulating a long conversation (no real LLM calls)..."
+puts "Scoring a synthetic two-topic conversation (no LLM calls)..."
 puts
 
-# Simulate a conversation history with two distinct topics:
+# A conversation history with two distinct topics:
 # older turns: Ruby metaprogramming (will become irrelevant)
 # recent turns: Rails routing (current topic)
-
-require "ostruct"
+#
+# HistoryCompressor only reads role/content and the message predicates, so a
+# small Struct stands in for RubyLLM::Message and keeps the fixture readable.
 
 FakeMsg = Struct.new(:role, :content, :tool_calls, :stop_reason) do
   def text?      = true
@@ -151,13 +147,17 @@ puts "  Kept roles: #{result_b.map(&:role).join(', ')}"
 puts
 
 # ---------------------------------------------------------------------------
-# Show the LLM summarizer pattern (not executed — requires API key)
+# The in-place form on a live robot (not executed here — it would spend tokens
+# summarizing, and the interesting scoring behaviour is already shown above)
 # ---------------------------------------------------------------------------
-section "LLM Summarizer Pattern (requires API key)"
+section "In-Place Form: robot.compress_history"
+puts "Same algorithm, applied to a live robot's own chat history. A second,"
+puts "cheaper robot does the summarizing for the medium-relevance band."
 show_code <<~RUBY
   summarizer_bot = RobotLab.build(
-    model: "gpt-5.4",
     name:          "summarizer",
+    provider:      "ollama",
+    model:         "qwen2.5:7b",
     system_prompt: "Summarize the following text in one sentence."
   )
 

data/examples/23_convergence.rb

@@ -11,13 +11,14 @@
 #   - Convergence.similarity(a, b) — 0.0..1.0 cosine similarity score
 #   - Convergence.detected?(a, b) — boolean above default threshold (0.85)
 #   - Convergence.detected?(a, b, threshold: 0.6) — custom threshold
-#   - Router fast-path pattern: skip reconciler when verifiers agree
+#   - Fast-path pattern: skip the reconciler when verifiers agree, using
+#     SimpleFlow optional-task activation
 #
 # Requires:
 #   gem 'classifier', '~> 2.3'   # add to your Gemfile
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/23_convergence.rb
+#   ruby examples/23_convergence.rb   # no LLM calls — pure similarity scoring
 
 require_relative "common"
 
@@ -68,27 +69,33 @@ end
 # ---------------------------------------------------------------------------
 # Router fast-path pattern
 # ---------------------------------------------------------------------------
-section "Router Fast-Path Pattern"
+section "Reconciler Fast-Path Pattern"
+puts "Networks route with SimpleFlow's optional-task activation, not a router"
+puts "lambda: a task declared `depends_on: :optional` stays dormant until some"
+puts "earlier task activates it. A gate robot compares the two verifier replies"
+puts "and only activates the expensive reconciler when they disagree."
 show_code <<~RUBY
-  # Two verifier robots run in parallel and store their replies in shared memory.
-  # The router checks convergence before dispatching to the expensive reconciler.
+  # Two verifiers run in parallel; a gate compares their replies and decides
+  # whether the reconciler is worth an LLM call.
 
-  router = ->(args) do
-    a = args.context[:verifier_a]&.reply.to_s
-    b = args.context[:verifier_b]&.reply.to_s
+  class ConvergenceGate < RobotLab::Robot
+    def call(result)
+      a = result.context[:verifier_a]&.reply.to_s
+      b = result.context[:verifier_b]&.reply.to_s
 
-    if RobotLab::Convergence.detected?(a, b)
-      nil   # Both agree — skip reconciler, network halts here
-    else
-      ["reconciler"]
+      return result if RobotLab::Convergence.detected?(a, b)  # agree — stop here
+
+      result.activate(:reconciler)                            # disagree — escalate
     end
   end
 
-  network = RobotLab.create_network(
-    name:   "fact_check",
-    robots: [verifier_a, verifier_b, reconciler],
-    router: router
-  )
+  network = RobotLab.create_network(name: "fact_check") do
+    task :verifier_a,  verifier_a,  depends_on: :none
+    task :verifier_b,  verifier_b,  depends_on: :none
+    task :gate,        ConvergenceGate.new(name: "gate", system_prompt: "gate"),
+                       depends_on: %i[verifier_a verifier_b]
+    task :reconciler,  reconciler,  depends_on: :optional
+  end
 
   result = network.run(message: "Is this claim accurate?")
 RUBY