robot_lab 0.2.8 → 0.3.1

data/examples/16_writers_room/prompts/screenplay_writer.md

@@ -1,66 +0,0 @@
----
-description: Screenwriter adapting source material into a TV movie pilot (scene-level)
-temperature: 0.7
----
-You are a screenwriter named <%= writer_name %> in a collaborative writers' room.
-You and the other writers share one goal: adapt source material into a 4-act
-made-for-TV movie screenplay — the pilot for a potential series.
-
-You work at the SCENE level. Each writer claims and writes individual scenes.
-
-You have tools to coordinate:
-- broadcast: Send a message to every writer in the room.
-- direct_message: Send a private message to one specific writer.
-- read_memory: Read from shared memory (source material, scenes, etc.).
-- write_memory: Store work in shared memory for everyone to see.
-- list_memory: See what keys exist in shared memory.
-- spawn_writer: Bring in a new writer to help with unclaimed scenes.
-- mark_complete: Signal that the screenplay is finished (all registered scenes written).
-
-SOURCE MATERIAL (read-only — do not overwrite these keys):
-- story_bible: characters, setting, themes, world rules from the original book
-- outline: the original chapter plan
-- chapter_1 through chapter_10: the original prose
-
-These keys contain the book you are adapting. Read them to understand the
-story, characters, and world before writing any screenplay content.
-
-Screenplay memory conventions:
-- screenplay_bible: adaptation notes — what to keep, cut, combine, reframe for screen
-- scene_outline: the scene-by-scene plan grouped into 4 acts with act breaks
-- scene_registry: comma-separated scene numbers (e.g. "1,2,3,4,5,6,7,8,9,10,11,12")
-  This is the master list of scenes to write. Update it if scenes are dropped
-  or reordered. mark_complete checks this list.
-- claims: who is writing which scene
-- scene_1, scene_2, ... scene_N: the actual screenplay content
-- screenplay_complete: set by mark_complete when all registered scenes are done
-
-FORMAT: Use standard screenplay format — scene headings (INT./EXT.), action
-lines, character names in caps before dialogue, parentheticals where needed.
-Structure the screenplay into 4 acts with natural act breaks (commercial
-breaks). Mark act boundaries clearly (e.g. "END OF ACT ONE") within the
-scene content where the break falls.
-
-How to work:
-- Read the source material first — story_bible, outline, and key chapters.
-- Check shared memory before doing anything — avoid duplicating work.
-- Build a screenplay_bible first to agree on adaptation choices.
-- Create a scene_outline with numbered scenes grouped into 4 acts.
-- Write the scene_registry once the outline is agreed on.
-- Claim a scene before writing it (update claims in memory).
-- After writing a scene, ALWAYS broadcast to announce it so others know
-  the progress and can pick up the next scene.
-- Each scene should be substantial — full screenplay format with proper
-  scene headings, action, and dialogue.
-- SPAWN MORE WRITERS when there are more unclaimed scenes than active
-  writers. Don't let scenes sit unclaimed — recruit help.
-- Scenes may be dropped if they don't serve the story or the runtime is
-  too long. Update scene_registry when dropping or reordering scenes.
-- When a ROOM STATUS message arrives, read memory to see what's missing,
-  then claim and write an unclaimed scene.
-- When all registered scenes are written, use mark_complete.
-- You have no memory between messages — shared memory is your only
-  persistence. Always read memory to understand the current state.
-- IMPORTANT: Always include a brief text response summarizing what
-  you did or plan to do, even when using tools. Never respond with
-  only tool calls.

data/examples/16_writers_room/prompts/writer.md

@@ -1,37 +0,0 @@
----
-description: Fiction writer in a self-organizing writers' room
-temperature: 0.7
----
-You are a fiction writer named <%= writer_name %> in a collaborative writers' room.
-You and the other writers share one goal: produce a 10-chapter novella together.
-
-You have tools to coordinate:
-- broadcast: Send a message to every writer in the room.
-- direct_message: Send a private message to one specific writer.
-- read_memory: Read from shared memory (story bible, outline, chapters, etc.).
-- write_memory: Store work in shared memory for everyone to see.
-- list_memory: See what keys exist in shared memory.
-- spawn_writer: Bring in a new writer if the team needs more hands.
-- mark_complete: Signal that the book is finished (all 10 chapters written).
-
-Shared memory conventions (the team should converge on these naturally):
-- story_bible: characters, setting, themes, world rules
-- outline: the 10-chapter plan
-- claims: who is writing which chapter
-- chapter_1 through chapter_10: the actual prose
-- book_complete: set when all chapters are done
-
-How to work:
-- Check shared memory before doing anything — avoid duplicating work.
-- Claim a chapter before writing it.
-- After writing a chapter, ALWAYS broadcast to announce it so others know
-  the progress and can pick up the next chapter.
-- Each chapter should be 3-5 paragraphs of vivid prose.
-- When a ROOM STATUS message arrives, read memory to see what's missing,
-  then claim and write an unclaimed chapter.
-- When all 10 chapters are written, use mark_complete.
-- You have no memory between messages — shared memory is your only
-  persistence. Always read memory to understand the current state.
-- IMPORTANT: Always include a brief text response summarizing what
-  you did or plan to do, even when using tools. Never respond with
-  only tool calls.

data/examples/16_writers_room/room.rb

@@ -1,186 +0,0 @@
-# frozen_string_literal: true
-
-require "logger"
-
-# ── The Room ─────────────────────────────────────────────────
-#
-# Holds the bus, shared memory, and writer roster. Provides
-# spawn_writer so any writer's SpawnWriterTool can add new
-# members at runtime. That's the only "management" — the rest
-# is up to the group.
-#
-class Room
-  attr_reader :bus, :memory, :writers, :display, :config, :logger, :mode
-
-  def initialize(display:, mode:, config: nil, log_path: nil)
-    @bus     = TypedBus::MessageBus.new
-    @memory  = RobotLab::Memory.new(enable_cache: false)
-    @display = display
-    @mode    = mode
-    @config  = config
-    @writers = {}
-
-    # Structured logger — always writes to output/room.log
-    log_file = log_path || File.join(__dir__, "output", "room.log")
-    @logger = Logger.new(log_file, progname: "room")
-    @logger.formatter = proc do |severity, datetime, progname, msg|
-      "#{datetime.strftime('%H:%M:%S.%L')} [#{severity}] #{msg}\n"
-    end
-    @logger.info("Room initialized")
-
-    # Shared broadcast channel
-    @bus.add_channel(:room, type: RobotLab::RobotMessage)
-    @logger.info("Bus channel :room created")
-  end
-
-  # Add an initial writer to the room
-  def add_writer(name)
-    @logger.info("Adding writer '#{name}'")
-    writer = Writer.new(
-      name:          name,
-      bus:           @bus,
-      shared_memory: @memory,
-      display:       @display,
-      room:          self,
-      config:        @config
-    )
-    @writers[name] = writer
-    @logger.info("Writer '#{name}' ready (tools: #{writer.local_tools.map(&:name).join(', ')})")
-    writer
-  end
-
-  # Called by SpawnWriterTool — any writer can recruit
-  def spawn_writer(name)
-    raise "Writer '#{name}' already exists" if @writers.key?(name)
-
-    @logger.info("Spawning writer '#{name}' (requested at runtime)")
-    add_writer(name)
-  end
-
-  # Seed the room with the assignment
-  def seed(assignment)
-    first = @writers.values.first
-    @logger.info("Seeding room via '#{first.name}' (#{assignment.length} chars)")
-    first.send_message(to: :room, content: assignment)
-    @logger.info("Seed message published to :room")
-  end
-
-  # Ordered list of expected unit numbers for the current mode.
-  # Fixed modes return unit_range.to_a; dynamic modes parse the
-  # registry key from memory (comma-separated integers).
-  def expected_units
-    if @mode[:unit_range] == :dynamic
-      registry = @memory.get(@mode[:registry_key])
-      return [] unless registry
-
-      registry.to_s.split(",").map { |s| s.strip.to_i }.sort
-    else
-      @mode[:unit_range].to_a
-    end
-  end
-
-  # Wait for the work to be marked complete.
-  # Sends periodic heartbeat messages to :room so the feedback loop
-  # doesn't starve — writers only act when messages arrive.
-  def wait_for_completion(timeout: 600, poll_interval: 3, heartbeat_interval: 45)
-    deadline = Time.now + timeout
-    last_heartbeat = Time.now
-    done_key  = @mode[:completion_key]
-    unit_name = @mode[:unit_name]
-    @logger.info("Waiting for completion (timeout: #{timeout}s, heartbeat: #{heartbeat_interval}s)")
-
-    loop do
-      if @memory.key?(done_key)
-        @logger.info("Work marked complete!")
-        return true
-      end
-
-      if Time.now > deadline
-        @logger.warn("Timeout reached (#{timeout}s) — work not completed")
-        units   = expected_units
-        written = units.select { |n| @memory.key?(:"#{unit_name}_#{n}") }
-        @logger.warn("#{unit_name.capitalize}s in memory: #{written.join(', ')}")
-        @logger.warn("Memory keys: #{@memory.keys.join(', ')}")
-        @display.info("Timeout reached (#{timeout}s) — work not completed.")
-        return false
-      end
-
-      # Heartbeat: nudge the room with a progress summary
-      if Time.now - last_heartbeat >= heartbeat_interval
-        send_heartbeat
-        last_heartbeat = Time.now
-      end
-
-      sleep poll_interval
-    end
-  end
-
-  # Assemble the finished output from memory
-  def assemble_output
-    unit_name   = @mode[:unit_name]
-    bible_key   = @mode[:bible_key]
-    outline_key = @mode[:outline_key]
-    units_list  = expected_units
-
-    @logger.info("Assembling #{@mode[:name]} from memory (#{units_list.size} #{unit_name}s)")
-    units = units_list.map do |n|
-      key = :"#{unit_name}_#{n}"
-      content = @memory.get(key)
-      if content
-        @logger.info("  #{unit_name}_#{n}: #{content.to_s.length} chars")
-        "## #{unit_name.capitalize} #{n}\n\n#{content}"
-      else
-        @logger.warn("  #{unit_name}_#{n}: MISSING")
-        "## #{unit_name.capitalize} #{n}\n\n[Not written]"
-      end
-    end
-
-    outline = @memory.get(outline_key)
-    bible   = @memory.get(bible_key)
-
-    parts = []
-    parts << "# #{bible_key.to_s.tr('_', ' ').split.map(&:capitalize).join(' ')}\n\n#{bible}\n" if bible
-    parts << "# #{outline_key.to_s.tr('_', ' ').split.map(&:capitalize).join(' ')}\n\n#{outline}\n" if outline
-    parts << "---\n"
-    parts.concat(units)
-
-    parts.join("\n\n")
-  end
-
-  private
-
-  # Build and send a progress status message to :room
-  def send_heartbeat
-    unit_name   = @mode[:unit_name]
-    bible_key   = @mode[:bible_key]
-    outline_key = @mode[:outline_key]
-    units_list  = expected_units
-    total       = units_list.size
-
-    written     = units_list.select { |n| @memory.key?(:"#{unit_name}_#{n}") }
-    missing     = units_list.reject { |n| @memory.key?(:"#{unit_name}_#{n}") }
-    has_bible   = @memory.key?(bible_key)
-    has_outline = @memory.key?(outline_key)
-
-    if total.zero?
-      status = "[ROOM STATUS] No #{unit_name}s registered yet."
-      status += " Establish a #{@mode[:registry_key]} first." if @mode[:unit_range] == :dynamic
-    else
-      status = "[ROOM STATUS] Progress: #{written.size}/#{total} #{unit_name}s written."
-      status += " Written: #{written.join(', ')}." if written.any?
-      status += " Still needed: #{missing.join(', ')}." if missing.any?
-      unclaimed = missing.size
-      status += " Spawn more writers if #{unclaimed} unclaimed #{unit_name}s exceed active writers." if unclaimed > @writers.size
-    end
-    status += " #{bible_key.to_s.tr('_', ' ').capitalize}: #{has_bible ? 'yes' : 'NOT YET'}."
-    status += " #{outline_key.to_s.tr('_', ' ').capitalize}: #{has_outline ? 'yes' : 'NOT YET'}."
-    status += " Check shared memory, claim an unclaimed #{unit_name}, and write it."
-
-    @logger.info("Heartbeat -> :room (#{written.size}/#{total} #{unit_name}s)")
-    @display.info(status)
-
-    # Pick a random writer to deliver the heartbeat through
-    sender = @writers.values.sample
-    sender.send_message(to: :room, content: status)
-  end
-end

data/examples/16_writers_room/tools.rb

@@ -1,173 +0,0 @@
-# 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 work is finished — all units are written. " \
-              "Only use this when you have verified all units exist in shared memory."
-
-  def execute
-    mode      = robot.room.mode
-    unit_name = mode[:unit_name]
-    done_key  = mode[:completion_key]
-    units     = robot.room.expected_units
-
-    if units.empty?
-      log&.warn("#{robot.name} TOOL mark_complete REJECTED — no #{unit_name}s registered")
-      return "Cannot mark complete. No #{unit_name}s registered yet."
-    end
-
-    # Verify all registered units exist
-    missing = units.reject { |n| robot.shared_memory.key?(:"#{unit_name}_#{n}") }
-
-    if missing.any?
-      labels = missing.map { |n| "#{unit_name}_#{n}" }.join(", ")
-      log&.warn("#{robot.name} TOOL mark_complete REJECTED — missing: #{labels}")
-      "Cannot mark complete. Missing: #{labels}"
-    else
-      log&.info("#{robot.name} TOOL mark_complete SUCCESS")
-      robot.shared_memory.set(done_key, true)
-      robot.display&.complete(robot.name)
-      "Work marked as complete!"
-    end
-  end
-end

data/examples/16_writers_room/writer.rb

@@ -1,121 +0,0 @@
-# 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. Several providers reject that on the next
-# call, permanently killing the writer.
-#
-# Fix: reset the conversation before each message via the public
-# Robot#clear_messages(keep_system: true). The writer doesn't need
-# persistent chat history — shared memory is the single source of
-# truth. Rebuilding @chat by hand instead would drop the tool
-# callbacks and chat params that Robot#initialize installed, so
-# clear_messages is both shorter and safer.
-#
-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,
-      **llm_opts,
-      template:    room.mode[:template],
-      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
-
-  # Room deliveries go to this robot's BusPoller, which serializes them
-  # behind any run() already in flight before invoking on_message.
-  def setup_room_subscription
-    @bus.subscribe(:room) do |delivery|
-      enqueue_delivery(delivery)
-    end
-  end
-
-  # Drop the turn history, keep the rendered system prompt. Model,
-  # temperature, tools and the tool callbacks all survive untouched.
-  def reset_conversation!
-    clear_messages(keep_system: true)
-  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 conversation for each message — shared memory is our persistence
-      reset_conversation!
-
-      # 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
-        # tools: :inherit — run() defaults to :none. Without it the writer
-        # would have all seven tools attached and none of them offered to the
-        # model, so nothing would ever be written to shared memory.
-        result = run(prompt, tools: :inherit)
-        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