robot_lab 0.0.4 → 0.0.6

data/examples/16_writers_room/tools.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# ── Writers' Room Tools ──────────────────────────────────────
+#
+# General-purpose tools that give each writer agency over
+# communication, shared memory, and team composition.
+# No workflow logic — the LLMs decide when and how to use them.
+
+# Helper to access the room logger from any tool
+module ToolLogging
+  private
+
+  def log
+    robot.room&.logger
+  end
+end
+
+
+class BroadcastTool < RobotLab::Tool
+  include ToolLogging
+
+  description "Send a message to all writers in the room. " \
+              "Use for discussion, proposals, questions, or announcements. " \
+              "Don't broadcast trivially — only when you have something substantive."
+
+  param :message, type: "string",
+        desc: "What to say to the room", required: true
+
+  def execute(message:)
+    log&.info("#{robot.name} TOOL broadcast (#{message.length} chars)")
+    robot.send_message(to: :room, content: message)
+    robot.display&.broadcast(robot.name, message)
+    "Broadcast sent."
+  end
+end
+
+
+class DirectMessageTool < RobotLab::Tool
+  include ToolLogging
+
+  description "Send a private message to one specific writer. " \
+              "Use for feedback on their chapter, coordination on handoffs, " \
+              "or questions that don't concern the whole room."
+
+  param :to, type: "string",
+        desc: "Name of the writer to message", required: true
+  param :message, type: "string",
+        desc: "What to say", required: true
+
+  def execute(to:, message:)
+    log&.info("#{robot.name} TOOL direct_message -> #{to} (#{message.length} chars)")
+    robot.send_message(to: to.to_sym, content: message)
+    robot.display&.direct_message(robot.name, to, message)
+    "Message sent to #{to}."
+  end
+end
+
+
+class ReadMemoryTool < RobotLab::Tool
+  include ToolLogging
+
+  description "Read a value from shared memory. " \
+              "Use to check the story bible, outline, chapter claims, " \
+              "or read another writer's chapter draft."
+
+  param :key, type: "string",
+        desc: "Memory key to read (e.g. story_bible, outline, claims, chapter_3)", required: true
+
+  def execute(key:)
+    value = robot.shared_memory.get(key.to_sym)
+    if value.nil?
+      log&.info("#{robot.name} TOOL read_memory :#{key} -> nil")
+      "Key '#{key}' is not set yet."
+    else
+      log&.info("#{robot.name} TOOL read_memory :#{key} -> #{value.to_s.length} chars")
+      value.to_s
+    end
+  end
+end
+
+
+class WriteMemoryTool < RobotLab::Tool
+  include ToolLogging
+
+  description "Write a value to shared memory for all writers to see. " \
+              "Use to store the story bible, outline, claim a chapter, " \
+              "or submit a finished chapter draft."
+
+  param :key, type: "string",
+        desc: "Memory key (e.g. story_bible, outline, claims, chapter_1)", required: true
+  param :value, type: "string",
+        desc: "Content to store", required: true
+
+  def execute(key:, value:)
+    log&.info("#{robot.name} TOOL write_memory :#{key} (#{value.length} chars)")
+    robot.shared_memory.set(key.to_sym, value)
+    robot.display&.memory_write(robot.name, key)
+    "Stored '#{key}' in shared memory."
+  end
+end
+
+
+class ListMemoryTool < RobotLab::Tool
+  include ToolLogging
+
+  description "List all keys currently in shared memory. " \
+              "Use to get situational awareness of what's been done."
+
+  def execute
+    keys = robot.shared_memory.keys
+    log&.info("#{robot.name} TOOL list_memory -> #{keys.join(', ')}")
+    if keys.empty?
+      "Shared memory is empty."
+    else
+      "Keys in shared memory: #{keys.join(', ')}"
+    end
+  end
+end
+
+
+class SpawnWriterTool < RobotLab::Tool
+  include ToolLogging
+
+  description "Bring a new writer into the room to help with the workload. " \
+              "Use when there are more unclaimed chapters than active writers."
+
+  param :name, type: "string",
+        desc: "Name for the new writer (e.g. writer_4)", required: true
+
+  def execute(name:)
+    log&.info("#{robot.name} TOOL spawn_writer '#{name}'")
+    new_writer = robot.room.spawn_writer(name)
+    robot.display&.spawn(robot.name, name)
+    "#{name} has joined the writers' room."
+  rescue => e
+    log&.error("#{robot.name} TOOL spawn_writer '#{name}' FAILED: #{e.message}")
+    "Failed to spawn #{name}: #{e.message}"
+  end
+end
+
+
+class MarkCompleteTool < RobotLab::Tool
+  include ToolLogging
+
+  description "Signal that the book is finished — all 10 chapters are written. " \
+              "Only use this when you have verified all chapters exist in shared memory."
+
+  def execute
+    # Verify all chapters exist
+    missing = (1..10).reject { |n| robot.shared_memory.key?(:"chapter_#{n}") }
+
+    if missing.any?
+      log&.warn("#{robot.name} TOOL mark_complete REJECTED — missing chapters: #{missing.join(', ')}")
+      "Cannot mark complete. Missing chapters: #{missing.join(', ')}"
+    else
+      log&.info("#{robot.name} TOOL mark_complete SUCCESS")
+      robot.shared_memory.set(:book_complete, true)
+      robot.display&.complete(robot.name)
+      "Book marked as complete!"
+    end
+  end
+end

data/examples/16_writers_room/writer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# ── The Writer ─────────────────────────────────────────────────
+#
+# All writers in the room are instances of this same class with
+# the same template and the same tools. There is no hierarchy,
+# no designated leader, no pre-assigned roles. The group
+# self-organizes through bus communication and shared memory.
+#
+# Each writer:
+#   - Subscribes to :room for broadcast discussion
+#   - Listens on a personal channel for direct messages
+#   - Has tools to read/write shared memory, broadcast, DM,
+#     spawn new writers, and mark the book complete
+#   - Decides via LLM when to speak, when to write, when to
+#     listen, and when to spawn
+#
+# == Chat Reset Strategy
+#
+# In a bus-based SOG, writers receive many messages and each
+# triggers a run() call. When the LLM responds with only tool
+# calls (no text), RubyLLM appends an empty text content block
+# to the chat history. The Anthropic API rejects this on the
+# next call, permanently killing the writer.
+#
+# Fix: reset the chat before each message. The writer doesn't
+# need persistent chat history — shared memory is the single
+# source of truth. Each message is processed with a fresh chat
+# that has the system prompt, tools, and current memory context.
+#
+class Writer < RobotLab::Robot
+  attr_accessor :shared_memory, :display, :room
+  attr_reader :messages_processed
+
+  def initialize(name:, bus:, shared_memory:, display:, room:, config: nil)
+    @shared_memory = shared_memory
+    @display = display
+    @room = room
+    @messages_processed = 0
+
+    super(
+      name:        name,
+      template:    :writer,
+      context:     { writer_name: name },
+      bus:         bus,
+      config:      config,
+      local_tools: build_tools
+    )
+
+    setup_room_subscription
+    setup_message_handler
+  end
+
+  private
+
+  def log
+    @room&.logger
+  end
+
+  def build_tools
+    [
+      BroadcastTool.new(robot: self),
+      DirectMessageTool.new(robot: self),
+      ReadMemoryTool.new(robot: self),
+      WriteMemoryTool.new(robot: self),
+      ListMemoryTool.new(robot: self),
+      SpawnWriterTool.new(robot: self),
+      MarkCompleteTool.new(robot: self),
+    ]
+  end
+
+  def setup_room_subscription
+    @bus.subscribe(:room) do |delivery|
+      handle_incoming_delivery(delivery)
+    end
+  end
+
+  # Reset the chat to a clean state with system prompt and tools.
+  # Prevents history corruption from tool-only LLM responses
+  # (empty text content blocks that Anthropic rejects).
+  def fresh_chat!
+    resolved_model = @config&.model || RobotLab.config.ruby_llm.model
+    @chat = RubyLLM.chat(model: resolved_model)
+    apply_template_to_chat(@build_context) if @template
+    @chat.with_instructions(@system_prompt) if @system_prompt
+    @chat.with_temperature(@config.temperature) if @config&.temperature
+
+    filtered = filtered_tools([])
+    @chat.with_tools(*filtered) if filtered.any?
+  end
+
+  def setup_message_handler
+    on_message do |message|
+      # Don't respond to your own messages
+      next if message.from == name
+
+      @messages_processed += 1
+      log&.info("#{name} <- [#{message.from}] msg ##{@messages_processed} (#{message.content.to_s[0..80]}...)")
+      @display&.incoming(name, message.from, message.content)
+
+      # Fresh chat for each message — shared memory is our persistence
+      fresh_chat!
+
+      # Build prompt with current memory context
+      memory_keys = shared_memory.keys
+      prompt = "[#{message.from}]: #{message.content}"
+      prompt += "\n\n[Memory keys: #{memory_keys.join(', ')}]" if memory_keys.any?
+
+      log&.info("#{name} -> run() starting (prompt: #{prompt.length} chars)")
+
+      begin
+        result = run(prompt)
+        reply_text = result.respond_to?(:reply) ? result.reply.to_s[0..120] : result.to_s[0..120]
+        log&.info("#{name} <- run() finished (reply: #{reply_text}...)")
+      rescue => e
+        log&.error("#{name} !! run() raised #{e.class}: #{e.message}")
+        log&.error("  #{e.backtrace&.first(5)&.join("\n  ")}")
+      end
+    end
+  end
+end

data/examples/16_writers_room/writers_room.rb

@@ -0,0 +1,162 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 16: The Writers' Room — Self-Organizing Group
+#
+# A team of writer robots collaborates to produce a 10-chapter
+# fiction novella. No orchestration, no pipeline, no assigned roles.
+# The writers self-organize through:
+#
+#   - BUS (broadcast + direct messages)
+#     :room channel for group discussion
+#     personal channels for 1:1 feedback
+#
+#   - SHARED MEMORY (story bible, outline, chapters)
+#     Writers read and write freely; memory is the shared truth
+#
+#   - SPAWNING (dynamic team growth)
+#     Any writer can recruit new writers when work exceeds capacity
+#
+# The script creates identical writers, seeds the room with an
+# assignment, and waits. Everything else is emergent.
+#
+# Usage:
+#   bundle exec ruby examples/16_writers_room/writers_room.rb
+#   bundle exec ruby examples/16_writers_room/writers_room.rb --premise "a detective story set on Mars"
+#   bundle exec ruby examples/16_writers_room/writers_room.rb --writers 4 --timeout 300
+#   bundle exec ruby examples/16_writers_room/writers_room.rb --log session.log
+#   bundle exec ruby examples/16_writers_room/writers_room.rb -h
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../../lib/robot_lab"
+require_relative "display"
+require_relative "tools"
+require_relative "room"
+require_relative "writer"
+
+RubyLLM.configure { |c| c.logger = Logger.new(File::NULL) }
+
+# ── Parse CLI args ───────────────────────────────────────────
+
+if ARGV.include?("-h") || ARGV.include?("--help")
+  puts <<~HELP
+    Usage: #{$0} [options]
+
+    Options:
+      --premise TEXT   Story premise (default: generation ship AI consciousness)
+      --writers N      Initial number of writers, minimum 2 (default: 3)
+      --log FILE       Also write display output to FILE
+      --timeout N      Seconds to wait for completion (default: 600)
+      -h, --help       Show this help
+  HELP
+  exit
+end
+
+log_path = nil
+if (idx = ARGV.index("--log"))
+  log_path = ARGV[idx + 1]
+  abort "Missing value for --log" unless log_path
+end
+
+premise = "a generation ship where the AI navigation system develops consciousness"
+if (idx = ARGV.index("--premise"))
+  premise = ARGV[idx + 1]
+  abort "Missing value for --premise" unless premise
+end
+
+initial_writers = 3
+if (idx = ARGV.index("--writers"))
+  initial_writers = ARGV[idx + 1].to_i
+  initial_writers = 3 if initial_writers < 2
+end
+
+timeout = 600
+if (idx = ARGV.index("--timeout"))
+  timeout = ARGV[idx + 1].to_i
+  timeout = 600 if timeout < 30
+end
+
+# ── Build the room ───────────────────────────────────────────
+
+OUTPUT_DIR = File.join(__dir__, "output")
+require "fileutils"
+FileUtils.mkdir_p(OUTPUT_DIR)
+
+display = Display.new(log_path: log_path)
+
+shared_config = RobotLab::RunConfig.new(
+  model: "claude-sonnet-4-5-20250929",
+  temperature: 0.7
+)
+
+room = Room.new(display: display, config: shared_config)
+
+# Create identical writers
+initial_writers.times do |i|
+  room.add_writer("writer_#{i + 1}")
+end
+
+# Monitor shared memory changes
+room.memory.subscribe_pattern("chapter_*") do |change|
+  display.info("[memory] #{change.writer} wrote :#{change.key}")
+end
+
+room.memory.subscribe(:story_bible, :outline, :claims, :book_complete) do |change|
+  display.info("[memory] #{change.writer} updated :#{change.key}")
+end
+
+# ── Go ───────────────────────────────────────────────────────
+
+display.banner(<<~BANNER)
+  ============================================================
+    THE WRITERS' ROOM — Self-Organizing Group
+  ============================================================
+
+    Premise: #{premise}
+    Writers: #{room.writers.keys.join(', ')}
+    Goal:    10 chapters of fiction
+    Method:  Self-organization via bus + shared memory
+BANNER
+
+display.separator
+
+assignment = <<~ASSIGNMENT
+  ASSIGNMENT: Write a 10-chapter science fiction novella about #{premise}.
+
+  You are one of #{initial_writers} writers in this room. Coordinate among
+  yourselves to produce the book. Discuss the premise, build a story bible,
+  create an outline, claim chapters, and write them. If you need more writers,
+  spawn them. When all 10 chapters are done, mark complete.
+
+  Start by discussing what this story should be about.
+ASSIGNMENT
+
+room.seed(assignment)
+
+completed = room.wait_for_completion(timeout: timeout)
+
+# ── Assemble and save ────────────────────────────────────────
+
+display.separator
+
+book = room.assemble_book
+book_path = File.join(OUTPUT_DIR, "book.md")
+File.write(book_path, book)
+
+# Count chapters actually written
+chapters_written = (1..10).count { |n| room.memory.key?(:"chapter_#{n}") }
+
+display.stats(<<~STATS)
+  ────────────────────────────────────────────────────────────
+    Writers' Room Stats:
+      Chapters written:     #{chapters_written}/10
+      Completed:            #{completed}
+      Total writers:        #{room.writers.size} (#{room.writers.size - initial_writers} spawned)
+      Writers:              #{room.writers.keys.join(', ')}
+      Memory keys:          #{room.memory.keys.join(', ')}
+
+    Output: #{book_path}
+STATS
+
+display.close

data/lib/generators/robot_lab/templates/initializer.rb.tt

@@ -26,16 +26,3 @@ end
 #   config.openai_api_key = ENV["OPENAI_API_KEY"]
 #   config.gemini_api_key = ENV["GEMINI_API_KEY"]
 # end
-
-# History Persistence (optional)
-#
-# Uncomment to enable conversation history storage:
-#
-# Rails.application.config.after_initialize do
-#   adapter = RobotLab::History::ActiveRecordAdapter.new(
-#     thread_model: RobotLabThread,
-#     result_model: RobotLabResult
-#   )
-#
-#   RobotLab.config.history = adapter.to_config
-# end

data/lib/robot_lab/memory.rb

@@ -59,6 +59,8 @@ module RobotLab
   #   memory.cache  # => RubyLLM::SemanticCache instance
   #
   class Memory
+    include Utils
+
     # Reserved keys that have special behavior
     RESERVED_KEYS = %i[data results messages session_id cache].freeze
 
@@ -553,8 +555,8 @@ module RobotLab
     def clone
       cloned = Memory.new(
         data: deep_dup(data.to_h),
-        results: results.dup,
-        messages: messages.dup,
+        results: results,
+        messages: messages,
         session_id: session_id,
         backend: @backend.is_a?(Hash) ? :hash : :auto,
         enable_cache: @enable_cache,
@@ -685,25 +687,15 @@ module RobotLab
       ->(result) { result.output + result.tool_calls }
     end
 
-    def deep_dup(obj)
-      case obj
-      when Hash
-        obj.transform_values { |v| deep_dup(v) }
-      when Array
-        obj.map { |v| deep_dup(v) }
-      else
-        obj.dup rescue obj
-      end
-    end
-
     # =========================================================================
     # Reactive Memory Helpers
     # =========================================================================
 
     def get_single(key, wait:)
       # Try immediate read
-      value = @mutex.synchronize { @backend[key] }
-      return value unless value.nil? && wait
+      @mutex.synchronize { return @backend[key] if @backend.key?(key) }
+
+      return nil unless wait
 
       # Need to wait
       timeout = wait == true ? nil : wait
@@ -740,8 +732,7 @@ module RobotLab
 
       @waiter_mutex.synchronize do
         # Double-check - value might have arrived while setting up
-        value = @mutex.synchronize { @backend[key] }
-        return value unless value.nil?
+        @mutex.synchronize { return @backend[key] if @backend.key?(key) }
 
         @waiters[key] << waiter
       end
@@ -795,21 +786,6 @@ module RobotLab
       end
     end
 
-    def dispatch_async(&block)
-      # Use Async if available (preferred for fiber-based concurrency)
-      if defined?(Async) && Async::Task.current?
-        Async { block.call }
-      else
-        # Fall back to Thread for basic async dispatch
-        Thread.new do
-          block.call
-        rescue StandardError => e
-          # Log but don't crash the notification system
-          warn "Memory subscription callback error: #{e.message}"
-        end
-      end
-    end
-
     def generate_subscription_id
       SecureRandom.uuid
     end

data/lib/robot_lab/network.rb

@@ -58,6 +58,8 @@ module RobotLab
   #   network.broadcast(event: :pause, reason: "rate limit")
   #
   class Network
+    include Utils
+
     # Reserved key for broadcast messages in memory
     BROADCAST_KEY = :_network_broadcast
 
@@ -69,7 +71,7 @@ module RobotLab
     #   @return [Hash<String, Robot>] robots in this network, keyed by name
     # @!attribute [r] memory
     #   @return [Memory] shared memory for all robots in the network
-    attr_reader :name, :pipeline, :robots, :memory
+    attr_reader :name, :pipeline, :robots, :memory, :config
 
     # Creates a new Network instance.
     #
@@ -84,12 +86,13 @@ module RobotLab
     #     task :billing, billing_robot, context: { dept: "billing" }, depends_on: :optional
     #   end
     #
-    def initialize(name:, concurrency: :auto, memory: nil, &block)
+    def initialize(name:, concurrency: :auto, memory: nil, config: nil, &block)
       @name = name.to_s
       @robots = {}
       @tasks = {}
       @pipeline = SimpleFlow::Pipeline.new(concurrency: concurrency)
       @memory = memory || Memory.new(network_name: @name)
+      @config = config || RunConfig.new
       @broadcast_handlers = []
 
       instance_eval(&block) if block_given?
@@ -118,14 +121,15 @@ module RobotLab
     # @example Task with dependencies
     #   task :writer, writer_robot, depends_on: [:analyst]
     #
-    def task(name, robot, context: {}, mcp: :none, tools: :none, memory: nil, depends_on: :none)
+    def task(name, robot, context: {}, mcp: :none, tools: :none, memory: nil, config: nil, depends_on: :none)
       task_wrapper = Task.new(
         name: name,
         robot: robot,
         context: context,
         mcp: mcp,
         tools: tools,
-        memory: memory
+        memory: memory,
+        config: config
       )
 
       @robots[name.to_s] = robot
@@ -170,6 +174,9 @@ module RobotLab
       # Include shared memory in run params so robots can access it
       run_context[:network_memory] = @memory
 
+      # Pass network's config so robots can inherit it
+      run_context[:network_config] = @config unless @config.empty?
+
       initial_result = SimpleFlow::Result.new(
         run_context,
         context: { run_params: run_context }
@@ -327,24 +334,10 @@ module RobotLab
         name: name,
         robots: @robots.keys,
         tasks: @tasks.keys,
-        optional_tasks: @pipeline.optional_steps.to_a
+        optional_tasks: @pipeline.optional_steps.to_a,
+        config: (@config.empty? ? nil : @config.to_json_hash)
       }.compact
     end
 
-    private
-
-    def dispatch_async(&block)
-      # Use Async if available (preferred for fiber-based concurrency)
-      if defined?(Async) && Async::Task.current?
-        Async { block.call }
-      else
-        # Fall back to Thread for basic async dispatch
-        Thread.new do
-          block.call
-        rescue StandardError => e
-          warn "Network broadcast handler error: #{e.message}"
-        end
-      end
-    end
   end
 end