robot_lab 0.3.0 → 0.3.1

data/examples/11_network_introspection.rb

@@ -1,239 +0,0 @@
-#!/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
-
-require_relative "common"
-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
-
-banner "Network Visualization & Introspection"
-
-# Shared RunConfig for all robots in this network
-shared_config = RobotLab::RunConfig.new(model: LLM[:default].model, temperature: 0.5)
-
-# Per-task RunConfig override for the writer (higher creativity)
-creative_config = RobotLab::RunConfig.new(temperature: 0.9)
-
-# Build robots (no LLM calls, just instances)
-classifier = RobotLab.build(**llm_opts, name: "classifier", system_prompt: "Classify input")
-analyst    = RobotLab.build(**llm_opts, name: "analyst",    system_prompt: "Analyze data")
-writer     = RobotLab.build(**llm_opts, name: "writer",     system_prompt: "Write summary")
-
-# Build network with RunConfig, dependencies, and per-task config
-network = RobotLab.create_network(name: "demo_pipeline", config: shared_config) do
-  task :classify, classifier, depends_on: :none
-  task :analyze, analyst, context: { depth: "deep" }, depends_on: [:classify]
-  task :write, writer, config: creative_config, depends_on: [:analyze]
-end
-
-# =============================================================================
-# Section 1: Visualization outputs
-# =============================================================================
-
-section "Section 1: Visualization"
-
-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
-# =============================================================================
-
-section "Section 2: Robot Access"
-
-# 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
-# =============================================================================
-
-section "Section 3: Dynamic Robot Addition"
-
-reviewer = RobotLab.build(**llm_opts, 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
-# =============================================================================
-
-section "Section 4: Network Introspection"
-
-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: RunConfig Introspection
-# =============================================================================
-
-section "Section 5: RunConfig Introspection"
-
-puts "Network RunConfig (shared defaults):"
-ap network.config.to_h
-puts
-
-puts "Merged effective config for :write task (network + task override):"
-effective = shared_config.merge(creative_config)
-ap effective.to_h
-puts "  model inherited from network, temperature overridden by task"
-puts
-
-# =============================================================================
-# Section 6: Broadcast
-# =============================================================================
-
-section "Section 6: Broadcast"
-
-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 7: Shared memory access
-# =============================================================================
-
-section "Section 7: Shared Network Memory"
-
-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
-
-hr
-puts "All sections completed without any LLM calls."

data/examples/12_message_bus.rb

@@ -1,67 +0,0 @@
-#!/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
-
-require_relative "common"
-
-MAX_ATTEMPTS = 5
-
-class Comedian < RobotLab::Robot
-  TEMP_START = 0.2
-  TEMP_STEP  = 0.2
-
-  def initialize(bus:)
-    super(name: "bob", **llm_opts, 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}"
-      send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
-    end
-  end
-
-  attr_reader :attempts
-end
-
-class ComedyCritic < RobotLab::Robot
-  def initialize(bus:)
-    super(name: "alice", **llm_opts, 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)
-
-banner "Tell Me a Funny Robot Joke"
-
-puts "Alice: Tell me a funny robot joke."
-puts
-alice.send_message(to: :bob, content: "Tell me a funny robot joke.")
-
-hr
-puts "Attempts: #{bob.attempts} / #{MAX_ATTEMPTS}"
-puts "Accepted: #{alice.accepted}"

data/examples/13_spawn.rb

@@ -1,85 +0,0 @@
-#!/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
-
-require_relative "common"
-
-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", **llm_opts, 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,
-      **llm_opts,
-      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
-
-banner "Spawning Specialist Robots"
-
-QUESTIONS.each_with_index do |question, i|
-  puts
-  puts "Question #{i + 1}: #{question}"
-  dispatcher.dispatch(question)
-end
-
-puts
-hr
-puts "Specialists spawned: #{dispatcher.spawned.keys.join(', ')}"
-puts "Total robots on bus: #{dispatcher.spawned.size + 1}"

data/examples/14_rusty_circuit/.envrc

@@ -1 +0,0 @@
-export ROBOT_LAB_TEMPLATE_PATH="${PWD}/prompts"

data/examples/14_rusty_circuit/.gitignore

@@ -1 +0,0 @@
-/output/

data/examples/14_rusty_circuit/README.md

@@ -1 +0,0 @@
-execute the open_mic.rb file

data/examples/14_rusty_circuit/comic.rb

@@ -1,149 +0,0 @@
-# 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."
-
-  parameter :new_persona, type: "string",
-        description: "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."
-
-  parameter :level, type: "number",
-        description: "Energy level from 0.1 (very controlled) to 1.0 (unhinged)"
-  parameter :reason, type: "string",
-        description: "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."
-
-  parameter :situation, type: "string",
-        description: "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",
-        **llm_opts,
-        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
-    robot.display&.working("Comic", "backstage with the coach")
-    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",
-      **llm_opts,
-      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."
-
-      # tools: :inherit — without it run() defaults to :none and the comic's
-      # three self-modification tools are never offered to the model, which
-      # kills the whole point of the demo.
-      result = run(prompt, tools: :inherit)
-      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