robot_lab 0.0.4 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d3bfa06c07301b03b01359a15a945374b135f2055c77396ad456a916917a742
-  data.tar.gz: 0b9e81d50841bf9a56d4efcc8f4175f34aa0e17702c89cc4bd5d4750631c0f68
+  metadata.gz: 1eaa090a87b2f82890dc8ee350bb1326b380c41d6560c3ae01e0ea1a4fc0d84a
+  data.tar.gz: 8232818730ba698d09ed9537adbc774f5d2ad84013942016e48ebad192a653c9
 SHA512:
-  metadata.gz: 15649fd320dd84530d49884900d99c2cdc98ddd5841948b052ed6b3a6f3d0fa9cec3e80636883f6d2bcd5b5a8ffe6b61ad681dc907faf5e881f48ac05ebef0fd
-  data.tar.gz: cdd136aad382247babb5639cf3a2b0b35db5086b33661823a6e00d8099f2a18a57325c3ed57f3474d23ee8f317f65c1f0b70911d349ad04f111d80cac03dd8c9
+  metadata.gz: ce75a3733e3d153196f85995c1363e542aa9b039f523cb15388a2d0d0f7a13d7ea26390a12abf6582680da5b119f1df8f6f35a7837a28a8b6f07f5aca72639db
+  data.tar.gz: c2c4f50e6352dc6018c8f0077549450e05adccb3eaa555236c46b131c557f69acf6f59ca6af12c823e429db777019bca684846338af273de2e2ce5587be5a976

data/CHANGELOG.md

@@ -11,6 +11,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.7] - 2026-02-17 [unreleased]
+
+### Added
+
+- **Screenplay mode** for Writers' Room — adapts a finished book into a 4-act made-for-TV movie screenplay (pilot for a series) using the same self-organizing group infrastructure
+  - **Mode Descriptor pattern** — `BOOK_MODE` and `SCREENPLAY_MODE` frozen hashes centralize all mode-variant values (template, unit name/range, completion key, bible/outline keys, output filename)
+  - **Dynamic scene registry** — screenplay writers work at the scene level with a `scene_registry` in shared memory (comma-separated scene numbers); scenes can be dropped or reordered as the adaptation takes shape
+  - **`Room#expected_units`** — public method that returns fixed range for book mode or parses the dynamic registry for screenplay mode; used by heartbeat, completion check, and assembly
+  - **`--screenplay-from PATH`** CLI flag — loads `memory.json` from a previous book run into shared memory before screenplay writers start
+  - **Memory dump** — book mode automatically saves all creative artifacts (story bible, outline, chapters) to `output/memory.json` after completion, enabling the book-to-screenplay pipeline
+  - **Screenplay writer prompt template** (`prompts/screenplay_writer.md`) — source material is read-only, writes to `screenplay_bible`, `scene_outline`, `scene_registry`, `claims`, `scene_1..N`; encourages spawning when unclaimed scenes exceed active writers
+  - **Heartbeat spawn nudging** — heartbeat messages now suggest spawning when unclaimed units outnumber active writers
+- **Output README** (`examples/16_writers_room/output/README.md`) documenting the creative works produced by robot teams (opus_001, opus_002, opus_002_screenplay)
+- **Opus 002** — second novella (*The Awakening of Meridian*) with session notes
+- **Opus 002 Screenplay** — first screenplay adaptation with adaptation discussion notes
+
+### Changed
+
+- Bumped version to 0.0.7
+- **Room class** now requires `mode:` parameter; `assemble_book` renamed to `assemble_output`; `wait_for_completion` and `send_heartbeat` read unit names, ranges, and keys from mode descriptor
+- **Writer class** reads template from `room.mode[:template]` instead of hardcoded `:writer`
+- **MarkCompleteTool** reads mode from `robot.room.mode` for unit range, unit name, and completion key; handles empty registry for dynamic modes
+- **Display#complete** uses mode-neutral "work" instead of "book"
+- Memory subscriptions in CLI are mode-aware (subscribe to mode-specific unit patterns and keys)
+- Updated Gemfile.lock dependencies (Nokogiri, Parser, Rack)
+
+## [0.0.6] - 2026-02-17 [unreleased]
+
+### Added
+
+- **Writers' Room example** (`examples/16_writers_room/`) — Self-Organizing Group (SOG) demo where identical writer robots collaborate to produce a 10-chapter fiction novella
+  - Writer class with `fresh_chat!` pattern to prevent RubyLLM empty text content block corruption in bus-based robots
+  - 7 tools: Broadcast, DirectMessage, ReadMemory, WriteMemory, ListMemory, SpawnWriter, MarkComplete
+  - Room class with bus, shared memory, writer roster, heartbeat-based progress nudging, and structured logging
+  - Display class with color-coded terminal output, word wrapping, and optional log file
+  - CLI with `--premise`, `--writers`, `--log`, `--timeout`, `-h`/`--help` options
+  - Shared prompt template (`prompts/writer.md`) — all writers use the same instructions with no hierarchy
+- **Network pipeline tests** (`test/robot_lab/network_pipeline_test.rb`) for sequential robot execution and memory sharing
+- **`dispatch_async` error handling** — exceptions inside async dispatch are now logged and contained instead of propagating
+
+### Changed
+
+- Bumped version to 0.0.6
+- **Removed `Errors` module** and related test file — unused error classes cleaned out
+- **Zeitwerk autoloading optimized** — streamlined loader configuration in `lib/robot_lab.rb`
+- Rakefile updated with `16_writers_room` entry point in `SUBDIR_ENTRY_POINTS`
+
+## [0.0.5] - 2026-02-17 [unreleased]
+
+### Added
+
+- **`RunConfig` class** (`lib/robot_lab/run_config.rb`) for shared operational defaults
+  - Field categories: LLM (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`), tools (`mcp`, `tools`), callbacks (`on_tool_call`, `on_tool_result`), infrastructure (`bus`, `enable_cache`)
+  - Keyword construction, block DSL, and method chaining
+  - Merge semantics: more-specific config's non-nil values win
+  - `apply_to(chat)` applies LLM fields to a RubyLLM chat
+  - `from_front_matter(metadata)` extracts config from template YAML front matter
+  - `to_h`, `to_json_hash` (skips Procs/IO), `empty?`, `key?`, `==`, `inspect`
+  - Full test suite (`test/robot_lab/run_config_test.rb`, 39 tests)
+- **`config:` parameter** on `Robot.new`, `Network.new`, `Network#task`, `RobotLab.build`, and `RobotLab.create_network` for passing RunConfig instances
+- **Configuration inheritance chain**: `RobotLab.config` (global) -> `network.config` -> task `config:` -> `robot.config` -> template front matter -> constructor kwargs
+- **`robot.config` / `network.config` accessors** (`attr_reader`) returning the effective RunConfig
+- **`RobotLab.configure`** block-style configuration method yielding the config object
+- **Bus processing guard** (`handle_incoming_delivery`) serializing message deliveries across bus-connected robots to prevent Async fiber re-entrancy corrupting chat message ordering
+- Documentation for RunConfig across README, configuration guide, network guide, and API reference
+- Updated examples (`03_network`, `08_llm_config`, `09_chaining`, `11_network_introspection`) demonstrating RunConfig usage
+
+### Changed
+
+- Bumped version to 0.0.5
+- **Template rendering refactored** to use `RunConfig.from_front_matter` instead of `apply_front_matter_config` — front matter config is now merged with the robot's RunConfig before applying to chat
+- **MCP/tools hierarchy resolution** now accepts `network_config:` parameter instead of directly accessing the network object, enabling RunConfig-driven configuration flow
+- **`dispatch_async`** simplified to exclusively use Async fibers, removing Thread-based fallback
+- **`Memory#get`** improved nil value handling — uses `@backend.key?()` instead of nil check for correct nil value storage and retrieval
+- **`Memory#clone`** optimized — results and messages are referenced directly instead of duplicated
+
 ## [0.0.4] - 2026-02-16 [unreleased]
 
 ### Added

data/README.md

@@ -187,6 +187,57 @@ robot = RobotLab.build(
 )
 ```
 
+### Shared Configuration with RunConfig
+
+`RunConfig` lets you define operational defaults that flow through the hierarchy: Network -> Robot -> Template -> Task -> Runtime. Use it to share LLM settings across multiple robots or an entire network.
+
+```ruby
+# Create a shared config
+shared = RobotLab::RunConfig.new(
+  model: "claude-sonnet-4",
+  temperature: 0.7,
+  max_tokens: 2000
+)
+
+# Apply to individual robots
+robot = RobotLab.build(
+  name: "writer",
+  system_prompt: "You are a creative writer.",
+  config: shared
+)
+
+# Apply to an entire network (all robots inherit these defaults)
+network = RobotLab.create_network(name: "pipeline", config: shared) do
+  task :analyzer, analyzer_robot, depends_on: :none
+  task :writer, writer_robot, depends_on: [:analyzer]
+end
+
+# Robot-specific kwargs always override the shared config
+robot = RobotLab.build(
+  name: "fast_bot",
+  system_prompt: "Be brief.",
+  config: shared,
+  temperature: 0.3  # overrides shared config's 0.7
+)
+```
+
+RunConfig supports keyword construction, block DSL, and merge semantics:
+
+```ruby
+# Block DSL
+config = RobotLab::RunConfig.new do |c|
+  c.model "claude-sonnet-4"
+  c.temperature 0.7
+end
+
+# Merge (more-specific wins)
+network_config = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+robot_config   = RobotLab::RunConfig.new(temperature: 0.9)
+effective      = network_config.merge(robot_config)
+effective.temperature  #=> 0.9
+effective.model        #=> "claude-sonnet-4"
+```
+
 ### Chaining Configuration
 
 Robots support method chaining to adjust configuration after creation:
@@ -375,7 +426,7 @@ class Comedian < RobotLab::Robot
     super(name: "bob", template: :comedian, bus: bus)
     on_message do |message|
       joke = run(message.content.to_s).last_text_content.strip
-      reply(message, joke)
+      send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
     end
   end
 end
@@ -402,7 +453,7 @@ Key features:
 
 - **Typed channels** — only `RobotMessage` objects are accepted (type enforcement via `typed_bus`)
 - **Auto-ACK** — `on_message { |message| }` auto-acknowledges; use `|delivery, message|` for manual ACK/NACK
-- **Reply correlation** — `reply(message, content)` tracks conversation threads via `in_reply_to`
+- **Reply correlation** — `send_reply(to:, content:, in_reply_to:)` tracks conversation threads
 - **Outbox tracking** — sent messages tracked in `robot.outbox` with status and replies
 - **Independent of Network** — bus communication works without a Network pipeline
 
@@ -451,17 +502,24 @@ Key features:
 
 ## Streaming
 
-Pass a block to `run` to receive real-time events during execution:
+Use a `Streaming::Context` with a publish callback to receive real-time events:
 
 ```ruby
-result = robot.run("Tell me a story") do |event|
+handler = lambda do |event|
   case event[:event]
-  when "text.delta"
+  when RobotLab::Streaming::Events::TEXT_DELTA
     print event[:data][:delta]
-  when "run.completed"
+  when RobotLab::Streaming::Events::RUN_COMPLETED
     puts "\nDone!"
   end
 end
+
+context = RobotLab::Streaming::Context.new(
+  run_id: SecureRandom.uuid,
+  message_id: SecureRandom.uuid,
+  scope: "robot",
+  publish: handler
+)
 ```
 
 ## Rails Integration

data/Rakefile

@@ -48,7 +48,8 @@ namespace :examples do
   # Map of subdirectory-based demos to their entry point scripts
   SUBDIR_ENTRY_POINTS = {
     "14_rusty_circuit" => "open_mic.rb",
-    "15_memory_network_and_bus" => "editorial_pipeline.rb"
+    "15_memory_network_and_bus" => "editorial_pipeline.rb",
+    "16_writers_room" => "writers_room.rb"
   }.freeze
 
   desc "Run all examples"

data/docs/api/core/index.md

@@ -12,21 +12,21 @@ classDiagram
         +model: String
         +template: String
         +tools: Array~Tool~
-        +run(state, network)
+        +run(message) Message
     }
 
     class Network {
         +name: String
         +robots: Hash
-        +router: Proc
-        +run(state)
+        +config: RunConfig
+        +run(message)
     }
 
-    class State {
-        +data: StateProxy
-        +results: Array
-        +messages: Array
-        +memory: Memory
+    class RunConfig {
+        +model: String
+        +temperature: Float
+        +merge(other) RunConfig
+        +apply_to(chat)
     }
 
     class Tool {
@@ -37,10 +37,13 @@ classDiagram
     }
 
     class Memory {
-        +remember(key, value)
-        +recall(key)
-        +forget(key)
-        +scoped(namespace)
+        +set(key, value)
+        +get(key)
+        +delete(key)
+        +data: StateProxy
+        +results: Array
+        +messages: Array
+        +session_id: String
     }
 
     class RobotMessage {
@@ -53,9 +56,11 @@ classDiagram
     }
 
     Network --> Robot : contains
+    Network --> RunConfig : uses
+    Robot --> RunConfig : uses
     Robot --> Tool : has
-    State --> Memory : has
-    Network --> State : uses
+    Robot --> Memory : uses
+    Network --> Memory : uses
     Robot ..> RobotMessage : sends/receives
 ```
 
@@ -65,10 +70,10 @@ classDiagram
 |-------|---------|
 | [Robot](robot.md) | LLM agent with personality, tools, and model configuration |
 | [Network](network.md) | Container for robots with routing and orchestration |
-| [State](state.md) | Conversation state with data, results, and memory |
+| RunConfig | Shared configuration for LLM, tools, callbacks, and infrastructure |
 | [Tool](tool.md) | Callable function with parameters and handler |
 | [AskUser](tool.md#built-in-askuser) | Built-in tool for terminal-based user interaction |
-| [Memory](memory.md) | Namespaced key-value store for sharing data |
+| [Memory](memory.md) | Reactive key-value store for sharing data |
 | RobotMessage | Typed envelope for bus-based inter-robot communication |
 
 ## Quick Examples
@@ -76,50 +81,40 @@ classDiagram
 ### Robot
 
 ```ruby
-robot = RobotLab.build do
-  name "assistant"
-  model "claude-sonnet-4"
-  template "You are helpful."
-
-  tool :greet do
-    parameter :name, type: :string
-    handler { |name:, **_| "Hello, #{name}!" }
-  end
-end
+robot = RobotLab.build(
+  name: "assistant",
+  model: "claude-sonnet-4",
+  system_prompt: "You are helpful.",
+  local_tools: [greet_tool]
+)
+
+result = robot.run("Hello!")
 ```
 
 ### Network
 
 ```ruby
-network = RobotLab.create_network do
-  name "my_network"
-  add_robot robot
-  router ->(args) { args.call_count.zero? ? :assistant : nil }
+network = RobotLab.create_network(name: "my_network") do
+  step :analyzer, analyzer_robot, depends_on: :none
+  step :writer, writer_robot, depends_on: [:analyzer]
 end
+
+result = network.run(message: "Process this")
 ```
 
-### State
+### Memory
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Hello",
-  data: { user_id: "123" }
-)
+memory = RobotLab.create_memory(data: { user_id: "123" })
+memory.set(:category, "billing")
+memory.get(:category)  # => "billing"
 ```
 
 ### Tool
 
 ```ruby
-tool = RobotLab::Tool.new(
+tool = RobotLab::Tool.create(
   name: "get_time",
-  description: "Get current time",
-  handler: ->(**, _) { Time.now.to_s }
-)
-```
-
-### Memory
-
-```ruby
-state.memory.remember("key", "value")
-value = state.memory.recall("key")
+  description: "Get current time"
+) { |**_| Time.now.to_s }
 ```