robot_lab 0.0.4 → 0.0.7

data/examples/16_writers_room/writers_room.rb

@@ -0,0 +1,256 @@
+#!/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.
+#
+# Modes:
+#   Book mode (default) — write an original 10-chapter novella
+#   Screenplay mode     — adapt a finished book into a 4-act TV movie pilot
+#
+# 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 --screenplay-from output/memory.json
+#   bundle exec ruby examples/16_writers_room/writers_room.rb -h
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require "json"
+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) }
+
+# ── Mode Descriptors ────────────────────────────────────────
+
+BOOK_MODE = {
+  name:            :book,
+  template:        :writer,
+  unit_name:       "chapter",
+  unit_range:      1..10,
+  completion_key:  :book_complete,
+  bible_key:       :story_bible,
+  outline_key:     :outline,
+  output_filename: "book.md"
+}.freeze
+
+SCREENPLAY_MODE = {
+  name:            :screenplay,
+  template:        :screenplay_writer,
+  unit_name:       "scene",
+  unit_range:      :dynamic,
+  registry_key:    :scene_registry,
+  completion_key:  :screenplay_complete,
+  bible_key:       :screenplay_bible,
+  outline_key:     :scene_outline,
+  output_filename: "screenplay.md"
+}.freeze
+
+# ── 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)
+      --screenplay-from PATH     Adapt a finished book into a screenplay using
+                                 memory dumped from a previous book-mode run
+      -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
+
+screenplay_source = nil
+if (idx = ARGV.index("--screenplay-from"))
+  screenplay_source = ARGV[idx + 1]
+  abort "Missing value for --screenplay-from" unless screenplay_source
+  abort "File not found: #{screenplay_source}" unless File.exist?(screenplay_source)
+end
+
+mode = screenplay_source ? SCREENPLAY_MODE : BOOK_MODE
+
+# ── 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, mode: mode, config: shared_config)
+
+# Load source material into memory for screenplay mode
+if screenplay_source
+  source_data = JSON.parse(File.read(screenplay_source))
+  source_data.each { |key, value| room.memory.set(key.to_sym, value) }
+  display.info("Loaded #{source_data.size} memory keys from #{screenplay_source}")
+end
+
+# Create identical writers
+initial_writers.times do |i|
+  room.add_writer("writer_#{i + 1}")
+end
+
+# Monitor shared memory changes
+room.memory.subscribe_pattern("#{mode[:unit_name]}_*") do |change|
+  display.info("[memory] #{change.writer} wrote :#{change.key}")
+end
+
+subscribe_keys = [mode[:bible_key], mode[:outline_key], :claims, mode[:completion_key]]
+subscribe_keys << mode[:registry_key] if mode[:registry_key]
+room.memory.subscribe(*subscribe_keys) do |change|
+  display.info("[memory] #{change.writer} updated :#{change.key}")
+end
+
+# ── Go ───────────────────────────────────────────────────────
+
+goal_label = mode[:name] == :book ? "10 chapters of fiction" : "4-act TV movie screenplay (dynamic scenes)"
+
+display.banner(<<~BANNER)
+  ============================================================
+    THE WRITERS' ROOM — Self-Organizing Group
+  ============================================================
+
+    Mode:    #{mode[:name]}
+    Premise: #{premise}
+    Writers: #{room.writers.keys.join(', ')}
+    Goal:    #{goal_label}
+    Method:  Self-organization via bus + shared memory
+BANNER
+
+display.separator
+
+if mode[:name] == :screenplay
+  assignment = <<~ASSIGNMENT
+    ASSIGNMENT: Adapt the source material into a 4-act made-for-TV movie screenplay
+    (pilot for a potential series). Work at the SCENE level — each writer claims
+    and writes individual scenes.
+
+    The source material is already loaded into shared memory. Read the story_bible,
+    outline, and chapter_1 through chapter_10 to understand the original book.
+
+    You are one of #{initial_writers} writers in this room. Coordinate among
+    yourselves to produce the screenplay:
+    1. Read the source material
+    2. Build a screenplay_bible (adaptation choices)
+    3. Create a scene_outline with numbered scenes grouped into 4 acts
+    4. Write the scene_registry (comma-separated scene numbers, e.g. "1,2,3,4,5,6,7,8,9,10,11,12")
+    5. Claim and write individual scenes (scene_1, scene_2, etc.)
+    6. Spawn more writers when unclaimed scenes exceed active writers
+    7. Mark complete when all registered scenes are written
+
+    Scenes may be dropped or reordered as the story takes shape — update the
+    scene_registry when that happens.
+
+    Start by reading the source material and discussing how to adapt it for screen.
+  ASSIGNMENT
+else
+  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
+end
+
+room.seed(assignment)
+
+completed = room.wait_for_completion(timeout: timeout)
+
+# ── Assemble and save ────────────────────────────────────────
+
+display.separator
+
+output_text = room.assemble_output
+output_path = File.join(OUTPUT_DIR, mode[:output_filename])
+File.write(output_path, output_text)
+
+# Dump memory for book mode (enables later screenplay adaptation)
+if mode[:name] == :book
+  memory_path = File.join(OUTPUT_DIR, "memory.json")
+  custom = room.memory.keys.each_with_object({}) do |k, h|
+    next if %i[results messages].include?(k)
+    h[k] = room.memory.get(k)
+  end
+  File.write(memory_path, JSON.pretty_generate(custom))
+  display.info("Memory dumped to #{memory_path}")
+end
+
+# Count units actually written
+unit_name     = mode[:unit_name]
+expected      = room.expected_units
+units_written = expected.count { |n| room.memory.key?(:"#{unit_name}_#{n}") }
+
+display.stats(<<~STATS)
+  ────────────────────────────────────────────────────────────
+    Writers' Room Stats:
+      Mode:                 #{mode[:name]}
+      #{unit_name.capitalize}s written:#{' ' * (10 - unit_name.length)}#{units_written}/#{expected.size}
+      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: #{output_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

data/lib/robot_lab/robot/bus_messaging.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Inter-robot communication via TypedBus.
+    #
+    # Expects the including class to provide:
+    #   @bus, @message_counter, @outbox, @message_handler,
+    #   @bus_subscriber_id, @bus_processing, @bus_queue, @name
+    #   and the `run` instance method
+    #
+    # == Processing Guard
+    #
+    # TypedBus delivers messages in concurrent Async fibers. When a robot's
+    # +run()+ yields during HTTP I/O, the Async scheduler can switch to
+    # another fiber delivering a new bus message to the same robot. This
+    # would interleave user messages between +tool_use+ / +tool_result+
+    # pairs in +@chat+, corrupting Anthropic API message ordering.
+    #
+    # The processing guard serializes delivery handling: deliveries that
+    # arrive while the robot is already processing are queued and drained
+    # sequentially after the current one completes.
+    #
+    module BusMessaging
+      # Send a message to another robot via the bus.
+      #
+      # @param to [String, Symbol] target robot's channel name
+      # @param content [String, Hash] message payload
+      # @return [RobotMessage] the sent message
+      # @raise [BusError] if no bus is configured
+      def send_message(to:, content:)
+        raise BusError, "No bus configured on robot '#{@name}'" unless @bus
+
+        @message_counter += 1
+        message = RobotMessage.build(id: @message_counter, from: @name, content: content)
+        @outbox[message.key] = { message: message, status: :sent, replies: [] }
+        publish_to_bus(to.to_sym, message)
+        message
+      end
+
+
+      # Send a reply to a specific message via the bus.
+      #
+      # @param to [String, Symbol] target robot's channel name
+      # @param content [String, Hash] reply payload
+      # @param in_reply_to [String] composite key of the message being replied to
+      # @return [RobotMessage] the reply message
+      # @raise [BusError] if no bus is configured
+      def send_reply(to:, content:, in_reply_to:)
+        raise BusError, "No bus configured on robot '#{@name}'" unless @bus
+
+        @message_counter += 1
+        reply = RobotMessage.build(id: @message_counter, from: @name, content: content, in_reply_to: in_reply_to)
+        publish_to_bus(to.to_sym, reply)
+        reply
+      end
+
+
+      # Register a custom handler for incoming bus messages.
+      #
+      # Block arity controls delivery handling:
+      # - 1 argument `|message|`: auto-acks before calling, auto-nacks on exception
+      # - 2 arguments `|delivery, message|`: manual mode, you call ack!/nack!
+      #
+      # @yield [message] or [delivery, message]
+      # @return [self]
+      def on_message(&block)
+        @message_handler = block
+        self
+      end
+
+
+      # Spawn a new robot on a shared bus.
+      #
+      # Creates a new Robot instance that shares this robot's bus,
+      # allowing it to immediately send and receive messages with
+      # all other robots on the bus. If no bus exists yet, one is
+      # created automatically and the parent robot is connected to it.
+      #
+      # @param name [String] unique name for the new robot
+      # @param system_prompt [String, nil] inline system prompt
+      # @param template [Symbol, nil] prompt_manager template
+      # @param local_tools [Array] tools for the new robot
+      # @param options [Hash] additional options passed to RobotLab.build
+      # @return [Robot] the newly created robot
+      #
+      # @example Spawn from a bus-less robot (bus and name created automatically)
+      #   bot  = RobotLab.build
+      #   bot2 = bot.spawn(system_prompt: "You are helpful.")
+      #
+      # @example Spawn a specialist from a message handler
+      #   on_message do |message|
+      #     specialist = spawn(
+      #       name: "fact_checker",
+      #       system_prompt: "You verify factual claims. Be concise."
+      #     )
+      #     specialist.send_message(to: name.to_sym, content: specialist.run(message.content).last_text_content)
+      #   end
+      #
+      def spawn(name: "robot", system_prompt: nil, template: nil, local_tools: [], **options)
+        ensure_bus
+
+        RobotLab.build(
+          name: name,
+          system_prompt: system_prompt,
+          template: template,
+          local_tools: local_tools,
+          bus: @bus,
+          **options
+        )
+      end
+
+
+      # Connect this robot to a message bus.
+      #
+      # If a bus is provided, the robot joins it. If no bus is provided
+      # and the robot doesn't already have one, a new bus is created.
+      # No-op if the robot is already on the given bus.
+      #
+      # @param bus [TypedBus::MessageBus, nil] bus to join (creates one if nil)
+      # @return [self]
+      #
+      # @example Join an existing bus
+      #   bot = RobotLab.build.with_bus(some_bus)
+      #
+      # @example Create a bus on demand
+      #   bot = RobotLab.build.with_bus
+      #
+      def with_bus(bus = nil)
+        return self if bus && @bus == bus
+
+        teardown_bus_channel if @bus
+        @bus = bus || @bus || TypedBus::MessageBus.new
+        setup_bus_channel
+        self
+      end
+
+      private
+
+      # Create a bus if one doesn't exist and connect this robot to it
+      def ensure_bus
+        with_bus unless @bus
+      end
+
+
+      # Create a typed channel on the bus and subscribe to it
+      def setup_bus_channel
+        channel_name = @name.to_sym
+        @bus.add_channel(channel_name, type: RobotMessage) unless @bus.channel?(channel_name)
+        @bus_subscriber_id = @bus.subscribe(channel_name) { |delivery| handle_incoming_delivery(delivery) }
+      end
+
+
+      # Unsubscribe from the bus channel
+      def teardown_bus_channel
+        channel_name = @name.to_sym
+        @bus.unsubscribe(channel_name, @bus_subscriber_id) if @bus_subscriber_id
+        @bus_subscriber_id = nil
+      end
+
+
+      # Dispatch incoming bus delivery to handler.
+      #
+      # Uses a processing guard to serialize delivery handling. When
+      # the robot is already processing a delivery (e.g., inside a
+      # run() call that yields during HTTP I/O), new deliveries are
+      # queued and drained sequentially after the current one completes.
+      #
+      # Auto-ack when the handler takes 1 arg (message only);
+      # manual ack/nack when the handler takes 2 args (delivery, message).
+      def handle_incoming_delivery(delivery)
+        if @bus_processing
+          @bus_queue << delivery
+          return
+        end
+
+        process_delivery(delivery)
+        drain_bus_queue
+      end
+
+
+      # Process a single delivery (called under the processing guard)
+      def process_delivery(delivery)
+        @bus_processing = true
+
+        message = delivery.message
+
+        # Correlate replies with outbox entries
+        if message.reply? && @outbox.key?(message.in_reply_to)
+          entry = @outbox[message.in_reply_to]
+          entry[:status] = :replied
+          entry[:replies] << message
+        end
+
+        if @message_handler
+          if @message_handler.arity == 1
+            delivery.ack!
+            @message_handler.call(message)
+          else
+            @message_handler.call(delivery, message)
+          end
+        else
+          handle_message_via_llm(delivery, message)
+        end
+      rescue => e
+        delivery.nack! if delivery.pending?
+        raise BusError, "Error handling bus message on robot '#{@name}': #{e.message}"
+      ensure
+        @bus_processing = false
+      end
+
+
+      # Drain queued deliveries sequentially
+      def drain_bus_queue
+        while (queued = @bus_queue.shift)
+          process_delivery(queued)
+        end
+      end
+
+
+      # Default handler: interpret message via LLM and reply
+      def handle_message_via_llm(delivery, message)
+        delivery.ack!
+        result = run(message.content.to_s)
+        send_reply(to: message.from.to_sym, content: result.last_text_content, in_reply_to: message.key)
+      end
+
+
+      # Publish a RobotMessage to a bus channel
+      def publish_to_bus(channel_name, message)
+        if defined?(Async::Task) && Async::Task.current?
+          @bus.publish(channel_name, message)
+        else
+          Async { @bus.publish(channel_name, message) }
+        end
+      end
+    end
+  end
+end