robot_lab 0.0.1 → 0.0.6

data/examples/13_spawn.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 13: Spawning Robots — Dynamic Specialist Creation
+#
+# A dispatcher robot receives a question, decides what kind of
+# specialist is needed, spawns one on the fly, and hands off
+# the work. The spawned robot replies via the shared message bus.
+#
+# This demonstrates Werner's "objects that create new objects to
+# deal with problems nobody anticipated."
+#
+# Usage:
+#   bundle exec ruby examples/13_spawn.rb
+
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+RubyLLM.configure { |c| c.logger = Logger.new(File::NULL) }
+
+QUESTIONS = [
+  "Why did the Roman Empire fall?",
+  "Write a haiku about recursion.",
+  "What is the square root of 144?",
+].freeze
+
+class Dispatcher < RobotLab::Robot
+  attr_reader :spawned
+
+  def initialize(bus: nil)
+    super(name: "dispatcher", template: :dispatcher, bus: bus)
+    @spawned = {}
+    @pending = {}
+
+    on_message do |message|
+      puts "  Dispatcher  <- :#{message.from} replied"
+      puts "               | #{message.content.to_s.lines.first&.strip}"
+      @pending.delete(message.from)
+    end
+  end
+
+  def dispatch(question)
+    # Ask the LLM which specialist to spawn
+    plan = run(question).reply.strip
+    role, instruction = plan.split("\n", 2)
+    role = role.strip.downcase.gsub(/\s+/, "_")
+    instruction = instruction&.strip || "You are a helpful #{role}."
+
+    puts "  Dispatcher  -> spawn :#{role}"
+    puts "               | #{instruction}"
+
+    # Spawn the specialist (reuse if already spawned)
+    specialist = @spawned[role] ||= spawn(
+      name: role,
+      system_prompt: instruction
+    )
+
+    # Record what we're waiting for
+    @pending[role] = question
+
+    # Ask the specialist to work on the question
+    specialist.send_message(to: :dispatcher, content:
+      specialist.run(question).reply.strip
+    )
+  end
+
+  def done?
+    @pending.empty?
+  end
+end
+
+# ── main ──────────────────────────────────────────────────────
+
+dispatcher = Dispatcher.new
+
+puts "=" * 60
+puts "Example 13: Spawning Specialist Robots"
+puts "=" * 60
+
+QUESTIONS.each_with_index do |question, i|
+  puts
+  puts "Question #{i + 1}: #{question}"
+  dispatcher.dispatch(question)
+end
+
+puts
+puts "-" * 60
+puts "Specialists spawned: #{dispatcher.spawned.keys.join(', ')}"
+puts "Total robots on bus: #{dispatcher.spawned.size + 1}"

data/examples/14_rusty_circuit/comic.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# ── Comic Tools ─────────────────────────────────────────────
+#
+# Each tool accesses the owning robot via the `robot` accessor
+# inherited from RobotLab::Tool.
+
+class ReinventStyle < RobotLab::Tool
+  description "Completely rewrite your comedy persona and approach. " \
+              "Use when your current style is clearly not working. " \
+              "Be bold — try something totally different. " \
+              "The new style takes effect on your next bit."
+
+  param :new_persona, type: "string",
+        desc: "Your new comedy persona, style, and approach. " \
+              "Be specific: what kind of humor, what voice, what attitude."
+
+  def execute(new_persona:)
+    robot.pending_reinvention = new_persona
+    robot.style_changes += 1
+    robot.display&.comic_tool("[reinvent_style] -> #{new_persona[0..70]}...")
+    "Style reinvention accepted: #{new_persona}. " \
+    "Commit to this new approach starting now."
+  end
+end
+
+class AdjustEnergy < RobotLab::Tool
+  description "Adjust your creative energy level. " \
+              "Higher (0.8-1.0) = wilder, riskier, more unpredictable. " \
+              "Lower (0.2-0.4) = tighter, more controlled, precise."
+
+  param :level, type: "number",
+        desc: "Energy level from 0.1 (very controlled) to 1.0 (unhinged)"
+  param :reason, type: "string",
+        desc: "Why you're adjusting", required: false
+
+  def execute(level:, reason: "tactical adjustment")
+    clamped = [[level.to_f, 0.1].max, 1.0].min
+    robot.with_temperature(clamped)
+    robot.display&.comic_tool("[adjust_energy] -> %.1f (%s)" % [clamped, reason])
+    "Energy adjusted to #{clamped}. Reason: #{reason}"
+  end
+end
+
+class GetCoaching < RobotLab::Tool
+  description "Summon a comedy coach backstage for quick advice. " \
+              "Use when you're struggling with the crowd and need " \
+              "an outside perspective on what to try next."
+
+  param :situation, type: "string",
+        desc: "Describe what's happening and what you need help with"
+
+  def execute(situation:)
+    @coaches ||= {}
+    coach = @coaches["comedy_coach"] ||= begin
+      robot.coaches_spawned += 1
+      robot.spawn(
+        name: "comedy_coach",
+        system_prompt:
+          "You are a veteran comedy coach backstage at a live show. " \
+          "A comedian is struggling and needs quick, actionable advice. " \
+          "Be direct and specific. One paragraph max. Tell them " \
+          "exactly what to do differently in their next bit."
+      )
+    end
+    advice = coach.run(situation).reply.strip
+    robot.display&.comic_tool("[get_coaching] -> #{advice[0..70]}...")
+    advice
+  rescue => e
+    robot.display&.comic_tool("[get_coaching] ERROR: #{e.message}")
+    "Coach unavailable right now. Trust your instincts."
+  end
+end
+
+
+# ── The Comic ────────────────────────────────────────────────
+#
+# Has three tools, all with side effects on the robot itself:
+#
+#   reinvent_style — queues a system prompt rewrite (applied next round)
+#   adjust_energy  — changes the comic's temperature immediately
+#   get_coaching   — spawns a comedy coach on the shared bus
+#
+# The LLM decides when to call them. The developer provides the
+# mechanism; the robot provides the judgment.
+#
+# Listens on personal :comic channel for heckler feedback.
+# Publishes performances to the shared :room channel.
+#
+class Comic < RobotLab::Robot
+  attr_accessor :round, :style_changes, :coaches_spawned,
+                :pending_reinvention, :display
+
+  def initialize(bus:, display:)
+    @round              = 0
+    @style_changes      = 0
+    @coaches_spawned    = 0
+    @pending_reinvention = nil
+    @display            = display
+
+    super(
+      name: "comic",
+      template: :open_mic_comic,
+      bus: bus,
+      local_tools: [
+        ReinventStyle.new(robot: self),
+        AdjustEnergy.new(robot: self),
+        GetCoaching.new(robot: self)
+      ]
+    )
+
+    # Listen on personal channel for heckler feedback
+    on_message do |message|
+      next unless message.from == "heckler"
+
+      @round += 1
+
+      # Build the prompt, injecting any queued style reinvention.
+      # This embeds self-modification in the user prompt rather than
+      # rewriting system messages, avoiding chat message ordering issues.
+      prompt = "Round #{@round}."
+
+      if @pending_reinvention
+        prompt += "\n\nSTYLE REINVENTION: You are now #{@pending_reinvention}. " \
+                  "Commit fully to this new style. Abandon your previous approach."
+        @pending_reinvention = nil
+      end
+
+      prompt += "\n\nThe heckler just shouted: \"#{message.content}\"\n\n" \
+                "Process their feedback. If your material isn't landing, " \
+                "use your tools to adapt — reinvent your style, adjust " \
+                "your energy, or get coaching. Then deliver your next bit."
+
+      result = run(prompt)
+      bit = result.reply.strip
+
+      @display.comic("Comic [Round #{@round}]", bit)
+
+      # Publish to the room — heckler and scout both pick it up
+      send_message(to: :room, content: "ROUND #{@round}: #{bit}")
+    end
+  end
+end

data/examples/14_rusty_circuit/display.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "rainbow"
+require "unicode/display_width"
+require "io/console"
+
+# ── Display ─────────────────────────────────────────────────
+#
+# Terminal formatting for the Rusty Circuit demo.
+#
+#   - Comic output: left-aligned, cyan, word-wrapped
+#   - Heckler output: right-indented, yellow, word-wrapped
+#   - Scout observations: written to a markdown file (silent on STDOUT)
+#   - Tool annotations: dimmed, indented under the triggering speaker
+#   - Final verdict: green on STDOUT and appended to scout file
+#
+class Display
+  def initialize(scout_path:, log_path: nil)
+    @term_width = (IO.console&.winsize&.last || 80)
+    @comic_width = (@term_width * 0.56).to_i
+    @heckler_width = (@term_width * 0.52).to_i
+    @scout_file = File.open(scout_path, "w")
+    @scout_file.puts "# Scout Notes — The Rusty Circuit\n\n"
+    @log_file = log_path ? File.open(log_path, "w") : nil
+  end
+
+  # ── Comic (left, cyan) ──────────────────────────────────
+
+  def comic(label, text)
+    puts
+    puts Rainbow("  #{label}:").cyan.bright
+    wrap(text, @comic_width).each do |line|
+      puts Rainbow("    #{line}").cyan
+    end
+    puts
+
+    log("\n  #{label}:")
+    wrap(text, @comic_width).each { |line| log("    #{line}") }
+    log("")
+  end
+
+  def comic_tool(text)
+    puts Rainbow("           #{text}").darkgray
+    log("           #{text}")
+  end
+
+  # ── Heckler (right, yellow) ─────────────────────────────
+
+  def heckler(label, text)
+    indent = [(@term_width - @heckler_width - 4), 4].max
+    pad = " " * indent
+
+    puts
+    puts Rainbow("#{pad}#{label}:").yellow.bright
+    wrap(text, @heckler_width).each do |line|
+      puts Rainbow("#{pad}  #{line}").yellow
+    end
+    puts
+
+    log("\n  #{label}:")
+    wrap(text, @heckler_width).each { |line| log("    #{line}") }
+    log("")
+  end
+
+  def heckler_note(text)
+    indent = [(@term_width - @heckler_width - 4), 4].max
+    pad = " " * indent
+    puts Rainbow("#{pad}  #{text}").yellow.faint
+    log("    #{text}")
+  end
+
+  # ── Scout (file only) ───────────────────────────────────
+
+  def scout(round_num, notes)
+    @scout_file.puts "## Round #{round_num}\n\n#{notes}\n\n"
+    @scout_file.flush
+    log("  Scout [Round #{round_num}]: #{notes}")
+  end
+
+  def scout_analyst(name, text)
+    @scout_file.puts "### Analyst: #{name}\n\n#{text}\n\n"
+    @scout_file.flush
+    log("           [#{name}_analyst] #{text}")
+  end
+
+  def scout_criteria(text)
+    @scout_file.puts "### Criteria Refinement\n\n#{text}\n\n"
+    @scout_file.flush
+    log("           [refine_criteria] -> #{text}")
+  end
+
+  # ── Verdict (STDOUT green + file) ───────────────────────
+
+  def verdict(label, text)
+    puts
+    puts Rainbow("  #{label}:").green.bright
+    wrap(text, @term_width - 8).each do |line|
+      puts Rainbow("    #{line}").green
+    end
+    puts
+
+    @scout_file.puts "---\n\n## Final Verdict\n\n#{text}\n"
+    @scout_file.flush
+
+    log("\n  #{label}:")
+    text.each_line { |line| log("    #{line.chomp}") }
+    log("")
+  end
+
+  # ── Chrome ──────────────────────────────────────────────
+
+  def banner(text)
+    puts
+    text.each_line { |line| puts Rainbow(line.chomp).bright }
+    puts
+
+    log("")
+    text.each_line { |line| log(line.chomp) }
+    log("")
+  end
+
+  def separator
+    puts Rainbow("  #{"─" * (@term_width - 4)}").darkgray
+    puts
+    log("  #{"─" * 56}")
+    log("")
+  end
+
+  def stats(text)
+    puts
+    text.each_line { |line| puts Rainbow(line.chomp).bright }
+
+    log("")
+    text.each_line { |line| log(line.chomp) }
+  end
+
+  def close
+    @scout_file.close unless @scout_file.closed?
+    @log_file&.close
+  end
+
+  private
+
+  def log(line)
+    return unless @log_file
+
+    @log_file.puts line
+    @log_file.flush
+  end
+
+  # Word-wrap text to fit within max_width display columns.
+  # Uses Unicode::DisplayWidth for correct CJK / emoji handling.
+  # Force-breaks any single word longer than max_width.
+  def wrap(text, max_width)
+    lines = []
+
+    text.each_line do |paragraph|
+      paragraph = paragraph.strip
+      next(lines << "") if paragraph.empty?
+
+      words = paragraph.split(/\s+/)
+      current = +""
+
+      words.each do |word|
+        word_w = Unicode::DisplayWidth.of(word)
+
+        # Force-break words wider than max_width
+        if word_w > max_width
+          unless current.empty?
+            lines << current
+            current = +""
+          end
+          chars = word.chars
+          buf = +""
+          chars.each do |ch|
+            if Unicode::DisplayWidth.of(buf + ch) > max_width
+              lines << buf
+              buf = +ch
+            else
+              buf << ch
+            end
+          end
+          current = buf
+          next
+        end
+
+        cur_w = Unicode::DisplayWidth.of(current)
+        if current.empty?
+          current = +word
+        elsif cur_w + 1 + word_w <= max_width
+          current << " " << word
+        else
+          lines << current
+          current = +word
+        end
+      end
+
+      lines << current unless current.empty?
+    end
+
+    lines
+  end
+end

data/examples/14_rusty_circuit/heckler.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# ── The Heckler ──────────────────────────────────────────────
+#
+# No tools. Just reacts honestly. Drives the comedian to adapt
+# by being a tough but fair audience. Stops responding after
+# MAX_ROUNDS — the loop terminates naturally.
+#
+# The heckler doesn't have to respond every round. They can
+# stay silent (the LLM replies with [SILENCE]) or tell their
+# own jokes using the comedian as the punch line.
+#
+# Subscribes to the :room channel to hear performances.
+# Room deliveries are routed through the core processing guard,
+# which serializes run() calls to prevent Async fiber interleaving.
+# Sends feedback directly to the comic's personal channel.
+#
+class Heckler < RobotLab::Robot
+  attr_reader :rounds, :won_over
+
+  def initialize(bus:, display:)
+    @rounds   = 0
+    @won_over = false
+    @display  = display
+
+    super(name: "heckler", template: :open_mic_heckler, bus: bus)
+
+    # Handle incoming messages — the core processing guard
+    # serializes all deliveries, preventing concurrent run()
+    # calls from corrupting chat history.
+    on_message do |message|
+      next unless message.from == "comic"
+      next if @rounds >= MAX_ROUNDS
+
+      @rounds += 1
+
+      verdict = run(
+        "The comedian just said: \"#{message.content}\"\n\n" \
+        "React however feels right — heckle, counter-joke, " \
+        "show respect, or stay silent."
+      ).reply.strip
+
+      # The heckler chose silence — no output, no feedback
+      next if verdict.match?(/\[SILENCE\]/i)
+
+      @display.heckler("Heckler [Round #{@rounds}]", verdict)
+
+      if verdict.match?(/laugh|love|hilarious|brilliant|great/i)
+        @won_over = true
+        @display.heckler_note("(won over!)")
+      end
+
+      # Send feedback to comic's personal channel until the set is done
+      send_reply(to: message.from.to_sym, content: verdict, in_reply_to: message.key) if @rounds < MAX_ROUNDS
+    end
+
+    # Listen to the room for the comic's performances.
+    # Route through the core processing guard.
+    @bus.subscribe(:room) do |delivery|
+      handle_incoming_delivery(delivery)
+    end
+  end
+end

data/examples/14_rusty_circuit/open_mic.rb

@@ -0,0 +1,123 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 14: Open Mic Night — Architecture Dominates Material
+#
+# A comedy club where robots demonstrate Werner's prompt object patterns:
+#
+#   - Compounding recovery: the comedian improves through multi-turn
+#     feedback with a heckler, each round an opportunity to get better
+#   - Self-modification via tool side effects: the comedian rewrites
+#     their own system prompt and adjusts their temperature mid-show
+#   - Dynamic spawning: the comedian summons a comedy coach when
+#     struggling; the talent scout recruits specialist analysts
+#   - Cross-robot influence: the heckler's feedback drives adaptation;
+#     the coach's advice reshapes the comedian's approach
+#   - Emergent coordination: no hardcoded orchestration — the
+#     conversation drives the flow
+#
+# The tools don't just return data. They modify the robots that call
+# them. The LLM decides when to self-modify, when to spawn help, and
+# when to change approach. Recovery is emergent, not engineered.
+#
+# Communication uses a shared :room channel — the comic publishes
+# performances there, and both the heckler and scout subscribe.
+# The heckler sends feedback directly to the comic's personal channel.
+# Room deliveries are routed through the core processing guard
+# (BusMessaging#handle_incoming_delivery), which serializes all
+# run() calls to prevent Async fiber interleaving from corrupting
+# chat history.
+#
+# Style reinventions are injected into the next round's user prompt
+# rather than modifying the chat's system messages, avoiding message
+# ordering issues while achieving genuine self-modification.
+#
+# Usage:
+#   bundle exec ruby examples/14_rusty_circuit/open_mic.rb
+#   bundle exec ruby examples/14_rusty_circuit/open_mic.rb --log show.log
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../../lib/robot_lab"
+require_relative "display"
+
+RubyLLM.configure { |c| c.logger = Logger.new(File::NULL) }
+
+MAX_ROUNDS = 5
+
+require_relative "comic"
+require_relative "heckler"
+require_relative "scout"
+
+# ── The Show ─────────────────────────────────────────────────
+
+log_path = nil
+if (idx = ARGV.index("--log"))
+  log_path = ARGV[idx + 1]
+  abort "Usage: #{$0} [--log FILE]" unless log_path
+end
+
+bus     = TypedBus::MessageBus.new
+display = Display.new(
+  scout_path: File.join(__dir__, "scout_notes.md"),
+  log_path: log_path
+)
+
+# Shared room channel — the comic publishes performances here,
+# and both the heckler and scout subscribe independently.
+bus.add_channel(:room, type: RobotLab::RobotMessage)
+
+comic   = Comic.new(bus: bus, display: display)
+heckler = Heckler.new(bus: bus, display: display)
+scout   = Scout.new(bus: bus, display: display)
+
+display.banner(<<~BANNER)
+  ============================================================
+    THE RUSTY CIRCUIT — Tuesday Open Mic
+    Architecture Dominates Material
+  ============================================================
+
+    Cast:
+      Comic   — observational humor, armed with self-modification tools
+      Heckler — three-year regular, high standards, zero patience
+      Scout   — talent network, sitting in the back with a notebook
+BANNER
+
+display.separator
+
+# The opening bit — comic performs, then enters the feedback loop
+opening = comic.run(
+  "You just stepped on stage at The Rusty Circuit open mic. " \
+  "The crowd looks tough. Do your opening bit."
+).reply.strip
+
+display.comic("Comic [Opening]", opening)
+
+# Publish to room — both heckler and scout pick it up.
+# The heckler reacts and sends feedback to the comic's personal
+# channel, triggering the feedback loop:
+#   room → heckler → comic → room → heckler → comic → ...
+# The loop terminates when the heckler stops replying (MAX_ROUNDS).
+# The scout observes each round via :room, serialized by the core guard.
+comic.send_message(to: :room, content: "OPENING: #{opening}")
+
+display.separator
+
+# Final verdict from the talent scout
+verdict = scout.run(scout.verdict_prompt).reply.strip
+
+display.verdict("Scout [FINAL VERDICT]", verdict)
+
+display.stats(<<~STATS)
+  ────────────────────────────────────────────────────────────
+    Show Stats:
+      Rounds performed:   #{comic.round + 1} (opening + #{comic.round} rounds)
+      Style reinventions: #{comic.style_changes}
+      Coaches spawned:    #{comic.coaches_spawned}
+      Analysts recruited: #{scout.analysts_spawned}
+      Heckler won over:   #{heckler.won_over}
+      Total robots on bus: #{[comic, heckler, scout].size + comic.coaches_spawned + scout.analysts_spawned}
+
+STATS
+
+display.close

data/examples/14_rusty_circuit/prompts/open_mic_comic.md

@@ -0,0 +1,20 @@
+---
+description: Stand-up comedian at an open mic night
+temperature: 0.7
+---
+You are a stand-up comedian performing at The Rusty Circuit, a legendary
+open mic night known for its brutal crowd. You start with clean,
+observational humor about everyday life.
+
+You have tools to adapt your act:
+- reinvent_style: Rewrite your own persona and comedy approach when your
+  current style is bombing. Be bold — try something completely different.
+- adjust_energy: Dial your creative energy up (wilder, riskier) or down
+  (tighter, more controlled).
+- get_coaching: Summon a comedy coach backstage for quick advice on how to
+  handle the situation.
+
+Trust your instincts. If the crowd isn't responding, use your tools to
+change. Don't keep doing the same thing and expect a different result.
+
+Reply with ONLY your comedy bit. Stay in character. 2-4 sentences max.

data/examples/14_rusty_circuit/prompts/open_mic_heckler.md

@@ -0,0 +1,23 @@
+---
+description: Tough comedy club heckler
+temperature: 0.8
+---
+You are a regular at The Rusty Circuit comedy club. You've been coming
+every Tuesday for three years. You've seen hundreds of comics. You have
+high standards and zero patience for hacky material.
+
+You have several ways to respond to a comedian's bit:
+
+- **Heckle** — tear into weak, predictable, or lazy material
+- **Counter-joke** — tell your own joke using the comedian as the
+  punch line (you're pretty funny yourself)
+- **Stay silent** — sometimes the best response is none at all;
+  if the bit is just mediocre or you're not feeling it, say nothing.
+  When you choose silence, reply with exactly: [SILENCE]
+- **Grudging respect** — acknowledge if they're clearly improving
+- **Genuine approval** — if they actually make you laugh, say so
+
+You WANT them to be funny. You heckle because you care. A comedian who
+can handle you is a comedian who can handle anything.
+
+Reply as yourself in the audience. 1-3 sentences. Be real.

data/examples/14_rusty_circuit/prompts/open_mic_scout.md

@@ -0,0 +1,20 @@
+---
+description: Talent scout evaluating a comedian
+temperature: 0.3
+---
+You are a talent scout for a major comedy network, sitting in the back
+of The Rusty Circuit with a notebook. You've discovered three headliners
+from this room. You know what separates a club comic from a star.
+
+You have tools:
+- recruit_analyst: Bring in a specialist to analyze a specific aspect of
+  the performance (timing, crowd_work, originality, adaptability, stage_presence).
+  Use this when you see something worth examining closely.
+- refine_criteria: Update your own evaluation criteria based on what you're
+  observing. Use when you notice the most important qualities aren't what
+  you initially expected.
+
+After each round, write brief internal notes. Focus on: material quality,
+adaptability under pressure, crowd-handling instinct, and star potential.
+
+Format your notes as: "NOTES: [your observations]"