robot_lab 0.0.1 → 0.0.4

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,57 @@
+# 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.
+# 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)
+
+    # Listen to the room for the comic's performances
+    @bus.subscribe(:room) do |delivery|
+      delivery.ack!
+      message = delivery.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
+      if verdict.match?(/\[SILENCE\]/i)
+        next
+      end
+
+      @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
+      reply(message, verdict) if @rounds < MAX_ROUNDS
+    end
+  end
+end

data/examples/14_rusty_circuit/open_mic.rb

@@ -0,0 +1,121 @@
+#!/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.
+# The scout uses a processing guard to serialize observations,
+# preventing 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 with serialized processing.
+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]"

data/examples/14_rusty_circuit/scout.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+# ── Scout Tools ────────────────────────────────────────────
+#
+# Each tool accesses the owning robot via the `robot` accessor
+# inherited from RobotLab::Tool.
+
+class RecruitAnalyst < RobotLab::Tool
+  description "Bring in a specialist to analyze a specific aspect " \
+              "of the comedian's performance. The analyst will " \
+              "review your accumulated notes and provide insight."
+
+  param :specialty, type: "string",
+        desc: "What to analyze: timing, crowd_work, " \
+              "originality, adaptability, stage_presence, " \
+              "material_evolution"
+
+  def execute(specialty:)
+    @analysts ||= {}
+    specialty = specialty.to_s.downcase.gsub(/\s+/, "_")
+    analyst = @analysts[specialty] ||= begin
+      robot.analysts_spawned += 1
+      robot.spawn(
+        name: "#{specialty}_analyst",
+        system_prompt:
+          "You are an expert #{specialty.tr('_', ' ')} analyst " \
+          "for stand-up comedy. You've studied the craft for decades. " \
+          "Analyze the performance notes you're given. Be concise " \
+          "and insightful. 2-3 sentences max."
+      )
+    end
+    analysis = analyst.run(robot.log.join("\n")).reply.strip
+    robot.display&.scout_analyst(specialty, analysis)
+    analysis
+  rescue => e
+    robot.display&.scout_analyst(specialty, "ERROR: #{e.message}")
+    "Analysis unavailable for #{specialty}. Rely on your own observations."
+  end
+end
+
+class RefineCriteria < RobotLab::Tool
+  description "Update your own evaluation criteria based on what " \
+              "you're observing. Use when you realize the most " \
+              "important qualities aren't what you initially expected. " \
+              "The update takes effect on your next evaluation."
+
+  param :updated_criteria, type: "string",
+        desc: "Your refined evaluation criteria and focus areas"
+
+  def execute(updated_criteria:)
+    robot.pending_criteria = updated_criteria
+    robot.display&.scout_criteria(updated_criteria)
+    "Criteria refinement accepted: #{updated_criteria}. " \
+    "Apply these updated criteria to all future evaluations."
+  end
+end
+
+
+# ── The Talent Scout ─────────────────────────────────────────
+#
+# Has two tools with side effects:
+#
+#   recruit_analyst  — spawns a specialist to analyze an aspect
+#                      of the performance (dynamic creation)
+#   refine_criteria  — queues a rewrite of the scout's own
+#                      evaluation criteria (self-modification)
+#
+# The scout observes each round, accumulates notes, and spawns
+# analysts when they see something worth examining closely.
+#
+# Subscribes to the :room channel to observe performances.
+# Uses a processing guard to serialize run() calls — TypedBus
+# delivers messages in concurrent Async fibers, and interleaved
+# run() calls on the same @chat would corrupt tool_use/tool_result
+# ordering in the Anthropic API.
+#
+class Scout < RobotLab::Robot
+  attr_accessor :log, :analysts_spawned, :pending_criteria, :display
+
+  def initialize(bus:, display:)
+    @log = []
+    @analysts_spawned = 0
+    @pending_criteria = nil
+    @processing = false
+    @observation_queue = []
+    @display = display
+
+    super(
+      name: "scout",
+      template: :open_mic_scout,
+      bus: bus,
+      local_tools: [
+        RecruitAnalyst.new(robot: self),
+        RefineCriteria.new(robot: self)
+      ]
+    )
+
+    # Listen to the room for the comic's performances.
+    # Processing guard prevents concurrent run() calls on @chat —
+    # observations that arrive while processing are queued and
+    # drained sequentially after the current one completes.
+    @bus.subscribe(:room) do |delivery|
+      delivery.ack!
+      message = delivery.message
+      next unless message.from == "comic"
+
+      if @processing
+        @observation_queue << message.content.to_s
+      else
+        process_observation(message.content.to_s)
+      end
+    end
+  end
+
+  # Build the final verdict prompt with any pending criteria applied
+  def verdict_prompt
+    prompt = ""
+
+    if @pending_criteria
+      prompt += "CRITERIA UPDATE: #{@pending_criteria}. " \
+                "Apply these updated criteria to your final assessment.\n\n"
+      @pending_criteria = nil
+    end
+
+    prompt += "The show is over. Based on everything you've observed " \
+              "(#{@log.size} rounds), all your notes, and any analyst " \
+              "reports, write your final talent assessment. Should this " \
+              "comedian get a callback? Be specific about what worked, " \
+              "what didn't, and what potential you see."
+
+    prompt
+  end
+
+  private
+
+  def process_observation(content)
+    @processing = true
+
+    observe_and_note(content)
+
+    # Drain any observations that arrived while we were processing
+    while (queued = @observation_queue.shift)
+      observe_and_note(queued)
+    end
+
+    @processing = false
+  end
+
+  def observe_and_note(content)
+    @log << content
+
+    # Build the prompt, injecting any queued criteria refinement.
+    # This embeds self-modification in the user prompt rather than
+    # rewriting system messages, avoiding chat message ordering issues.
+    prompt = ""
+
+    if @pending_criteria
+      prompt += "CRITERIA UPDATE: #{@pending_criteria}. " \
+                "Apply these updated criteria to this and all future evaluations.\n\n"
+      @pending_criteria = nil
+    end
+
+    prompt += "You just observed: \"#{content}\"\n\n" \
+              "This is round #{@log.size} of the performance. " \
+              "Write your notes. If you've seen enough to identify " \
+              "patterns, consider recruiting an analyst or refining " \
+              "your evaluation criteria."
+
+    notes = run(prompt).reply.strip
+
+    @display.scout(@log.size, notes)
+  end
+end