robot_lab 0.0.1 → 0.0.6

data/examples/10_memory.rb

@@ -0,0 +1,331 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 10: Advanced Memory Operations
+#
+# Demonstrates the Memory API without making any LLM calls. Covers:
+#   - StateProxy for method-style data access
+#   - Key subscriptions with MemoryChange objects
+#   - Pattern subscriptions
+#   - Unsubscribe
+#   - Key enumeration (keys, all_keys, key?)
+#   - Serialization (to_h, from_hash, to_json) with amazing_print
+#   - Serialization round-trip verification with hashdiff
+#   - Clone for isolated copies
+#   - Delete with reserved key protection
+#   - Clear vs reset
+#
+# Usage:
+#   bundle exec ruby examples/10_memory.rb
+
+# Configure template path before loading
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+require "json"
+require "amazing_print"
+require "hashdiff"
+
+puts "=" * 70
+puts "Example 10: Advanced Memory Operations"
+puts "=" * 70
+puts
+
+# =============================================================================
+# Section 1: StateProxy for method-style access
+# =============================================================================
+
+puts "--- Section 1: StateProxy for Method-Style Access ---"
+puts
+
+memory = RobotLab.create_memory(
+  data: { category: nil, priority: "low" },
+  enable_cache: false
+)
+
+puts "Initial data:"
+ap memory.data.to_h
+puts
+
+# StateProxy allows method-style access to the :data hash
+memory.data.category = "billing"
+
+puts "After memory.data.category = 'billing':"
+ap memory.data.to_h
+puts
+
+# Bracket-style also works
+memory.data[:priority] = "high"
+puts "After memory.data[:priority] = 'high':"
+ap memory.data.to_h
+puts
+
+# =============================================================================
+# Section 2: Subscriptions and MemoryChange
+# =============================================================================
+
+puts "--- Section 2: Subscriptions and MemoryChange ---"
+puts
+
+changes = []
+
+sub_id = memory.subscribe(:status) do |change|
+  changes << change
+end
+
+puts "Subscribed to :status (sub_id: #{sub_id[0..7]}...)"
+
+# Set current_writer so the MemoryChange knows who wrote
+memory.current_writer = "classifier"
+memory.set(:status, "processing")
+
+# Give the async callback time to fire
+sleep 0.1
+
+if changes.any?
+  change = changes.first
+  puts "Change received:"
+  ap change.to_h
+  puts "  created?: #{change.created?}"
+  puts "  updated?: #{change.updated?}"
+end
+
+# Update the same key to see an 'updated' change
+memory.set(:status, "complete")
+sleep 0.1
+
+if changes.size > 1
+  puts
+  puts "Second change (update):"
+  ap changes.last.to_h
+  puts "  created?: #{changes.last.created?}"
+  puts "  updated?: #{changes.last.updated?}"
+end
+puts
+
+# =============================================================================
+# Section 3: Pattern subscriptions
+# =============================================================================
+
+puts "--- Section 3: Pattern Subscriptions ---"
+puts
+
+pattern_changes = []
+
+pattern_sub_id = memory.subscribe_pattern("analysis:*") do |change|
+  pattern_changes << change
+end
+
+puts "Subscribed to pattern 'analysis:*'"
+
+memory.current_writer = "analyst"
+memory.set(:"analysis:sentiment", { score: 0.8 })
+memory.set(:"analysis:entities", ["Ruby", "LLM"])
+memory.set(:unrelated_key, "ignored")
+
+sleep 0.1
+
+puts "Pattern matched #{pattern_changes.size} changes (expected 2):"
+pattern_changes.each do |change|
+  ap({ change.key => change.value })
+end
+puts
+
+# =============================================================================
+# Section 4: Unsubscribe
+# =============================================================================
+
+puts "--- Section 4: Unsubscribe ---"
+puts
+
+count_before = changes.size
+memory.unsubscribe(sub_id)
+puts "Unsubscribed from :status"
+
+memory.set(:status, "archived")
+sleep 0.1
+
+puts "Changes after unsubscribe: #{changes.size} (was #{count_before}, should be same)"
+puts
+
+# =============================================================================
+# Section 5: Key management
+# =============================================================================
+
+puts "--- Section 5: Key Management ---"
+puts
+
+puts "memory.keys (non-reserved):"
+ap memory.keys
+puts
+
+puts "memory.all_keys (includes reserved: data, results, messages, session_id, cache):"
+ap memory.all_keys
+puts
+
+puts "memory.key?(:status) = #{memory.key?(:status)}"
+puts "memory.key?(:nope)   = #{memory.key?(:nope)}"
+puts
+
+# =============================================================================
+# Section 6: Serialization round-trip
+# =============================================================================
+
+puts "--- Section 6: Serialization Round-Trip ---"
+puts
+
+hash = memory.to_h
+puts "memory.to_h:"
+ap hash
+puts
+
+json_str = memory.to_json
+puts "memory.to_json length: #{json_str.length} chars"
+puts
+
+# Round-trip via from_hash
+restored = RobotLab::Memory.from_hash(hash)
+
+puts "Restored memory from hash:"
+ap restored.to_h
+puts
+
+# Use hashdiff to verify the round-trip preserved everything
+diff = Hashdiff.diff(hash, restored.to_h)
+if diff.empty?
+  puts "Round-trip verification: PERFECT (no differences)"
+else
+  puts "Round-trip differences:"
+  diff.each do |change|
+    op, path, *values = change
+    case op
+    when "+"
+      puts "  + #{path}: #{values.first.inspect}"
+    when "-"
+      puts "  - #{path}: #{values.first.inspect}"
+    when "~"
+      puts "  ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+    end
+  end
+end
+puts
+
+# =============================================================================
+# Section 7: Clone for isolation
+# =============================================================================
+
+puts "--- Section 7: Clone for Isolation ---"
+puts
+
+cloned = memory.clone
+cloned.set(:isolated_key, "only in clone")
+
+puts "cloned.key?(:isolated_key)  = #{cloned.key?(:isolated_key)}"
+puts "memory.key?(:isolated_key)  = #{memory.key?(:isolated_key)}  (isolated!)"
+puts
+
+# Show exactly what differs between clone and original
+diff = Hashdiff.diff(memory.to_h, cloned.to_h)
+puts "Diff (original vs clone):"
+diff.each do |change|
+  op, path, *values = change
+  case op
+  when "+"
+    puts "  + #{path}: #{values.first.inspect}"
+  when "-"
+    puts "  - #{path}: #{values.first.inspect}"
+  when "~"
+    puts "  ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+  end
+end
+puts
+
+# =============================================================================
+# Section 8: Delete and reserved key protection
+# =============================================================================
+
+puts "--- Section 8: Delete and Reserved Key Protection ---"
+puts
+
+before_delete = memory.to_h
+memory.delete(:status)
+
+puts "After memory.delete(:status):"
+diff = Hashdiff.diff(before_delete, memory.to_h)
+diff.each do |change|
+  op, path, *values = change
+  case op
+  when "-"
+    puts "  - #{path}: #{values.first.inspect}"
+  end
+end
+puts
+
+begin
+  memory.delete(:data)
+rescue ArgumentError => e
+  puts "memory.delete(:data) raises: #{e.message}"
+end
+puts
+
+# =============================================================================
+# Section 9: Clear vs Reset
+# =============================================================================
+
+puts "--- Section 9: Clear vs Reset ---"
+puts
+
+memory.set(:temp1, "value1")
+memory.set(:temp2, "value2")
+
+puts "Before clear:"
+before_clear = memory.to_h
+ap before_clear
+puts
+
+memory.clear
+
+puts "After clear (non-reserved keys removed):"
+after_clear = memory.to_h
+ap after_clear
+puts
+
+puts "Diff (before clear vs after clear):"
+Hashdiff.diff(before_clear, after_clear).each do |change|
+  op, path, *values = change
+  case op
+  when "+"
+    puts "  + #{path}: #{values.first.inspect}"
+  when "-"
+    puts "  - #{path}: #{values.first.inspect}"
+  when "~"
+    puts "  ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+  end
+end
+puts
+
+before_reset = memory.to_h
+memory.reset
+
+puts "After reset (full reset to initial state):"
+after_reset = memory.to_h
+ap after_reset
+puts
+
+puts "Diff (before reset vs after reset):"
+Hashdiff.diff(before_reset, after_reset).each do |change|
+  op, path, *values = change
+  case op
+  when "+"
+    puts "  + #{path}: #{values.first.inspect}"
+  when "-"
+    puts "  - #{path}: #{values.first.inspect}"
+  when "~"
+    puts "  ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+  end
+end
+puts
+
+puts "=" * 70
+puts "All sections completed without any LLM calls."
+puts "=" * 70

data/examples/11_network_introspection.rb

@@ -0,0 +1,253 @@
+#!/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
+
+# Shared RunConfig for all robots in this network
+shared_config = RobotLab::RunConfig.new(model: "claude-sonnet-4", 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(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 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
+# =============================================================================
+
+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: RunConfig Introspection
+# =============================================================================
+
+puts "--- Section 5: RunConfig Introspection ---"
+puts
+
+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
+# =============================================================================
+
+puts "--- Section 6: 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 7: Shared memory access
+# =============================================================================
+
+puts "--- Section 7: 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}"
+      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", 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}"