robot_lab 0.0.4 → 0.0.7

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

@@ -0,0 +1,66 @@
+---
+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

@@ -0,0 +1,37 @@
+---
+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

@@ -0,0 +1,186 @@
+# 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

@@ -0,0 +1,173 @@
+# 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

@@ -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:    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
+
+  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