robot_lab 0.3.0 → 0.5.0

data/examples/14_rusty_circuit/display.rb

@@ -1,217 +0,0 @@
-# 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
-
-  # ── Liveness ────────────────────────────────────────────
-  #
-  # The scout writes its notes to a file, so a scout turn produces NO
-  # terminal output at all — and a scout turn is 1-4 sequential LLM calls
-  # (observe, then any tool round-trips, then a spawned analyst's own run).
-  # On a local model that is minutes of dead-silent terminal, which reads
-  # as a hang. These lines prove the show is still moving.
-
-  def working(who, what)
-    puts Rainbow("  · #{who} #{what}…").darkgray
-    $stdout.flush
-    log("  · #{who} #{what}...")
-  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

@@ -1,65 +0,0 @@
-# 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 handed to the robot's BusPoller via
-# enqueue_delivery, which serializes run() calls so Async fiber
-# interleaving can't corrupt chat history.
-# 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", **llm_opts, 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. Deliveries go to
-    # the robot's own BusPoller, which serializes them behind any run()
-    # already in flight before handing them to the on_message handler.
-    @bus.subscribe(:room) do |delivery|
-      enqueue_delivery(delivery)
-    end
-  end
-end

data/examples/14_rusty_circuit/open_mic.rb

@@ -1,132 +0,0 @@
-#!/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 handed to each robot's BusPoller via
-# BusMessaging#enqueue_delivery, which serializes all run() calls so
-# Async fiber interleaving can't corrupt 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.
-#
-# RUNTIME: this is the most expensive example in the suite. A full show is
-# ~30 LLM calls (16 minimum, plus a round-trip per tool call and a full run
-# for every robot the comic or scout spawns). On a 20B+ local model at ~60s
-# per call that is 30+ minutes. Long silent stretches are the scout thinking,
-# not a hang — it writes notes to output/scout_notes.md rather than STDOUT,
-# so the "· Scout …" lines are your liveness signal.
-#
-# For a demo you can watch in a few minutes, point it at a smaller model:
-#   LLM_PROFILE=small bundle exec ruby examples/14_rusty_circuit/open_mic.rb
-#
-# 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 "../common"
-require_relative "display"
-
-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__, "output", "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.",
-  tools: :inherit
-).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
-display.working("Scout", "writing the final verdict")
-verdict = scout.run(scout.verdict_prompt, tools: :inherit).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

@@ -1,20 +0,0 @@
----
-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

@@ -1,23 +0,0 @@
----
-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

@@ -1,20 +0,0 @@
----
-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

@@ -1,165 +0,0 @@
-# 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."
-
-  parameter :specialty, type: "string",
-        description: "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",
-        **llm_opts,
-        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
-    robot.display&.working("Scout", "consulting the #{specialty.tr('_', ' ')} analyst")
-    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."
-
-  parameter :updated_criteria, type: "string",
-        description: "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.
-# Room deliveries are handed to the robot's BusPoller via
-# BusMessaging#enqueue_delivery, which serializes all run() calls so
-# Async fiber interleaving can't corrupt chat history.
-#
-class Scout < RobotLab::Robot
-  attr_accessor :log, :analysts_spawned, :pending_criteria, :display
-
-  def initialize(bus:, display:)
-    @log = []
-    @analysts_spawned = 0
-    @pending_criteria = nil
-    @display = display
-
-    super(
-      name: "scout",
-      **llm_opts,
-      template: :open_mic_scout,
-      bus: bus,
-      local_tools: [
-        RecruitAnalyst.new(robot: self),
-        RefineCriteria.new(robot: self)
-      ]
-    )
-
-    # 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"
-      observe_and_note(message.content.to_s)
-    end
-
-    # Listen to the room for the comic's performances. Deliveries go to
-    # the robot's own BusPoller, which serializes them behind any run()
-    # already in flight before handing them to the on_message handler.
-    @bus.subscribe(:room) do |delivery|
-      enqueue_delivery(delivery)
-    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 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."
-
-    # The scout's notes go to a file, so announce the turn on STDOUT first —
-    # otherwise this is several minutes of silent terminal on a local model.
-    @display.working("Scout", "taking notes on round #{@log.size}")
-
-    # tools: :inherit — run() defaults to :none, which would leave
-    # recruit_analyst and refine_criteria attached but never offered.
-    notes = run(prompt, tools: :inherit).reply.strip
-
-    @display.scout(@log.size, notes)
-  end
-end