robot_lab 0.0.1 → 0.0.4

data/examples/11_network_introspection.rb

@@ -0,0 +1,230 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 11: Network Visualization & Introspection
+#
+# Demonstrates network inspection and visualization without making any
+# LLM calls. Covers:
+#   - to_mermaid() — Mermaid diagram export
+#   - to_dot()     — Graphviz DOT export
+#   - execution_plan() — text execution order
+#   - visualize()  — ASCII pipeline visualization
+#   - robot(name) / [name] — access individual robots
+#   - available_robots() — list all robots
+#   - add_robot() — dynamically add a robot
+#   - to_h() — network introspection hash (via amazing_print)
+#   - Task-specific config (context:, depends_on:)
+#   - broadcast() and on_broadcast
+#
+# Usage:
+#   bundle exec ruby examples/11_network_introspection.rb
+
+# Configure template path before loading
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+require "amazing_print"
+require "tempfile"
+
+# On macOS + iTerm2, render DOT as a PNG and display inline via imgcat.
+# Returns true if the image was displayed, false otherwise.
+def render_dot_image(dot_source)
+  return false unless RUBY_PLATFORM.include?("darwin")
+
+  dot_cmd  = `which dot 2>/dev/null`.chomp
+  imgcat   = File.expand_path("~/.iterm2/imgcat")
+  imgcat   = `which imgcat 2>/dev/null`.chomp unless File.executable?(imgcat)
+
+  return false unless File.executable?(dot_cmd) && File.executable?(imgcat)
+  return false unless ENV["TERM_PROGRAM"] == "iTerm.app"
+
+  Tempfile.create(["pipeline", ".png"]) do |png|
+    IO.popen([dot_cmd, "-Tpng", "-o", png.path], "w") { |io| io.write(dot_source) }
+
+    if $?.success? && File.size(png.path) > 0
+      system(imgcat, png.path)
+      true
+    else
+      false
+    end
+  end
+end
+
+puts "=" * 70
+puts "Example 11: Network Visualization & Introspection"
+puts "=" * 70
+puts
+
+# Build robots (no LLM calls, just instances)
+classifier = RobotLab.build(name: "classifier", system_prompt: "Classify input")
+analyst    = RobotLab.build(name: "analyst",    system_prompt: "Analyze data")
+writer     = RobotLab.build(name: "writer",     system_prompt: "Write summary")
+
+# Build network with dependencies and per-task config
+network = RobotLab.create_network(name: "demo_pipeline") do
+  task :classify, classifier, depends_on: :none
+  task :analyze, analyst, context: { depth: "deep" }, depends_on: [:classify]
+  task :write, writer, depends_on: [:analyze]
+end
+
+# =============================================================================
+# Section 1: Visualization outputs
+# =============================================================================
+
+puts "--- Section 1: Visualization ---"
+puts
+
+mermaid = network.to_mermaid
+if mermaid
+  puts "Mermaid diagram:"
+  puts mermaid
+  puts
+end
+
+dot = network.to_dot
+if dot
+  puts "Graphviz DOT:"
+  puts dot
+  puts
+
+  if render_dot_image(dot)
+    puts "(Rendered pipeline graph above via Graphviz + imgcat)"
+    puts
+  end
+end
+
+plan = network.execution_plan
+if plan
+  puts "Execution plan:"
+  puts plan
+  puts
+end
+
+ascii = network.visualize
+if ascii
+  puts "ASCII visualization:"
+  puts ascii
+  puts
+end
+
+# If none of the visualization methods returned output, note it
+unless mermaid || dot || plan || ascii
+  puts "(Visualization methods returned nil — depends on simple_flow version)"
+  puts
+end
+
+# =============================================================================
+# Section 2: Robot access
+# =============================================================================
+
+puts "--- Section 2: Robot Access ---"
+puts
+
+# Access by task name with robot() method
+# Note: robots are keyed by task name (the first arg to task()), not robot.name
+puts "network.robot('classify').name  = #{network.robot('classify').name.inspect}"
+
+# Access with [] shorthand
+puts "network['analyze'].name         = #{network['analyze'].name.inspect}"
+
+# Also works with symbols
+puts "network[:write].name            = #{network[:write].name.inspect}"
+puts
+
+# List all robots
+puts "available_robots:"
+ap network.available_robots.map(&:name)
+puts
+
+# =============================================================================
+# Section 3: Dynamic robot addition
+# =============================================================================
+
+puts "--- Section 3: Dynamic Robot Addition ---"
+puts
+
+reviewer = RobotLab.build(name: "reviewer", system_prompt: "Review output")
+network.add_robot(reviewer)
+
+puts "After add_robot(reviewer):"
+ap network.available_robots.map(&:name)
+puts
+
+# Attempting to add a duplicate raises an error
+begin
+  network.add_robot(reviewer)
+rescue ArgumentError => e
+  puts "Duplicate add_robot raises: #{e.message}"
+end
+puts
+
+# =============================================================================
+# Section 4: Network introspection
+# =============================================================================
+
+puts "--- Section 4: Network Introspection ---"
+puts
+
+puts "network.to_h:"
+ap network.to_h
+puts
+
+# Individual robot introspection
+puts "network['classify'].to_h:"
+ap network["classify"].to_h
+puts
+
+puts "network['analyze'].to_h:"
+ap network["analyze"].to_h
+puts
+
+# =============================================================================
+# Section 5: Broadcast
+# =============================================================================
+
+puts "--- Section 5: Broadcast ---"
+puts
+
+broadcast_messages = []
+
+network.on_broadcast do |msg|
+  broadcast_messages << msg
+end
+
+puts "Registered broadcast handler"
+
+network.broadcast(event: :demo, message: "Hello from network!")
+
+# Give async handler time to fire
+sleep 0.1
+
+if broadcast_messages.any?
+  puts "Broadcast received:"
+  ap broadcast_messages.first
+else
+  puts "(No broadcast received — handler may be async)"
+end
+puts
+
+# =============================================================================
+# Section 6: Shared memory access
+# =============================================================================
+
+puts "--- Section 6: Shared Network Memory ---"
+puts
+
+puts "network.memory is a #{network.memory.class}"
+puts "network.memory.network_name = #{network.memory.network_name.inspect}"
+
+# Robots in a network share this memory during run()
+network.memory.set(:demo_key, "shared value")
+puts "network.memory.get(:demo_key) = #{network.memory.get(:demo_key).inspect}"
+puts
+
+puts "network.memory.to_h:"
+ap network.memory.to_h
+puts
+
+puts "=" * 70
+puts "All sections completed without any LLM calls."
+puts "=" * 70

data/examples/12_message_bus.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 12: Message Bus — Converging on a Funny Robot Joke
+#
+# Alice tasks Bob to tell a robot joke. Alice uses her LLM to
+# evaluate each joke. If she's not impressed she asks Bob to try
+# again. The loop continues until Alice approves or MAX_ATTEMPTS.
+#
+# Usage:
+#   bundle exec ruby examples/12_message_bus.rb
+
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+RubyLLM.configure { |c| c.logger = Logger.new(File::NULL) }
+
+MAX_ATTEMPTS = 5
+
+class Comedian < RobotLab::Robot
+  TEMP_START = 0.2
+  TEMP_STEP  = 0.2
+
+  def initialize(bus:)
+    super(name: "bob", template: :comedian, bus: bus, temperature: TEMP_START)
+    @attempts = 0
+    on_message do |message|
+      @attempts += 1
+      temp = [TEMP_START + TEMP_STEP * (@attempts - 1), 1.0].min
+      with_temperature(temp)
+      joke = run(message.content.to_s).reply.strip
+      puts "  Bob  [##{@attempts}, t=#{"%.1f" % temp}]: #{joke}"
+      reply(message, joke)
+    end
+  end
+
+  attr_reader :attempts
+end
+
+class ComedyCritic < RobotLab::Robot
+  def initialize(bus:)
+    super(name: "alice", template: :comedy_critic, bus: bus)
+    @accepted = false
+    @rounds   = 0
+    on_message do |message|
+      @rounds += 1
+      verdict = run("Evaluate this joke:\n\n#{message.content}").reply.strip
+      puts "  Alice: #{verdict}"
+      puts
+      @accepted = verdict.start_with?("FUNNY")
+      send_message(to: :bob, content: "Not funny enough. Try again.") unless @accepted || @rounds >= MAX_ATTEMPTS
+    end
+  end
+
+  attr_reader :accepted
+end
+
+bus   = TypedBus::MessageBus.new
+bob   = Comedian.new(bus: bus)
+alice = ComedyCritic.new(bus: bus)
+
+puts "=" * 60
+puts "Example 12: Tell Me a Funny Robot Joke"
+puts "=" * 60
+puts
+
+puts "Alice: Tell me a funny robot joke."
+puts
+alice.send_message(to: :bob, content: "Tell me a funny robot joke.")
+
+puts "-" * 60
+puts "Attempts: #{bob.attempts} / #{MAX_ATTEMPTS}"
+puts "Accepted: #{alice.accepted}"

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