robot_lab 0.0.1 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a73bb0d9c45aa5f2f904e744774ecb3396027fa17a7c099a1ede7ac57598929
-  data.tar.gz: 8ff58ce299752cb0ff12365637070d71f35b011613a62b01a62d2fe43523a87c
+  metadata.gz: db26fa8aa3d47eb49face5b344cd1b41ed6e148a0460514b54913b5973ca9cc1
+  data.tar.gz: 79f2a71535ddaabd6f2a7c5dceaf3aefad10e3e51b4c0ccbd04fbe82c7804f57
 SHA512:
-  metadata.gz: afa598bbaea859d6f70f6bef21c936fc4f6260cf15c8af786dbaee5ce4d71c4d24e9f4e63a243e9a3321d2659f04cd6fab86f19568852b3cbd659eb9f4b339a1
-  data.tar.gz: 77ea74d0251124766263e3baf64f80889a56ecffa248a1ac612cd0ea1ea495ee090a3830a575090fb5f13dfac55d3c10a0097c182f57cc5a47c3167b5cb4e29f
+  metadata.gz: 832389808ec464678849736bb0d9fceca5dd67a5a3fa1e4c0486367bdf20a389257f4bfdeeb3afc9ca8619168274eb2a7cbed2c0376e358c902030ee26b105de
+  data.tar.gz: fb57b2e6cb329f6c116cbd7cb81a60bb68a9daeddc6e45a1f859690cc7f44ff3074eb4dfcdf0240b6a95f3786d992fc31c6edc3ed61fd2f838b435a19b550876

data/.github/workflows/deploy-github-pages.yml

@@ -1,4 +1,4 @@
-name: Deploy HTM Documentation to GitHub Pages
+name: Deploy Documentation to GitHub Pages
 on:
   push:
     branches:
@@ -41,12 +41,12 @@ jobs:
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
 
+      - name: Build MkDocs site
+        run: mkdocs build
+
       - name: Deploy to GitHub Pages
-        run: |
-          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
-            echo "Deploying from main branch"
-            mkdocs gh-deploy --force --clean
-          else
-            echo "Deploying from develop branch"
-            mkdocs gh-deploy --force --clean
-          fi
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

data/.irbrc

@@ -0,0 +1,6 @@
+begin
+  load File.expand_path('lib/robot_lab.rb', __dir__)
+rescue LoadError => e
+  $stderr.puts "[robot_lab] #{e.message}"
+  $stderr.puts "[robot_lab] Run `bundle exec irb` to load RobotLab"
+end

data/CHANGELOG.md

@@ -11,6 +11,146 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`AskUser` tool** for human-in-the-loop interactions
+  - Supports open-ended text, multiple choice, and default values
+  - IO sourced from `robot.input`/`robot.output` (defaults to `$stdin`/`$stdout`)
+  - Full test suite (`test/robot_lab/ask_user_test.rb`)
+- **`Robot#input` / `Robot#output` accessors** for configurable IO streams
+- **`reply` alias** for `RobotResult#last_text_content` — shorter, more natural API
+- **`.irbrc`** for loading RobotLab in project-level IRB sessions
+- **`wait_until` test helper** replacing flaky `sleep`-based assertions in async tests
+- Documentation for AskUser tool across API reference, guides, and examples
+
+### Changed
+
+- Bumped version to 0.0.4
+- **Made Rails dependencies optional** — removed `railties`, `activerecord`, `state_machines`, `state_machines-activemodel`, `state_machines-activerecord` from gemspec hard dependencies; moved to Gemfile `:test` group
+- Replaced `require 'active_support'` with targeted `require 'active_support/core_ext/module/delegation'` — only loads what ruby_llm actually needs
+- Added `activesupport >= 7.0` as explicit gemspec dependency with comment explaining it's required by ruby_llm (undeclared upstream)
+- **Tool JSON schema keys are now symbolized** via `deep_symbolize_keys` in `Tool#to_json_schema`
+- Updated all examples to use `reply` alias instead of `last_text_content`
+- Replaced `sleep`-based test assertions with `wait_until` helper in memory, waiter, and robot tests
+- Disabled branch coverage in SimpleCov except in CI
+
+### Fixed
+
+- Gem install conflict (`activesupport` version mismatch) when running outside Bundler
+- IRB loading issue where `require_relative` was a no-op due to partial load in `$LOADED_FEATURES` — switched to `load`
+- Robot tests for `send_message` now register a message handler on the receiver to avoid TypedBus warnings
+
+## [0.0.3] - 2026-02-15 [unreleased]
+
+### Added
+
+- **Self-contained templates** with extended YAML front matter support
+  - `robot_name` — override robot name from template
+  - `description` — set robot description from template
+  - `tools` — declare tool class names (resolved via `Object.const_get` at build time)
+  - `mcp` — declare MCP server configurations
+  - Constructor-provided values always take precedence over front matter
+- **Editorial pipeline example** (`15_memory_network_and_bus/`) demonstrating multi-stage workflow with network, memory, and bus coordination
+  - OS-specific writer robots, editor, and editor-in-chief roles
+  - New prompt templates: `os_advocate`, `os_editor`, `os_chief`
+- Rakefile support for running subdirectory-based examples with `SUBDIR_ENTRY_POINTS` mapping
+
+### Changed
+
+- Bumped version to 0.0.3
+- Refactored Comic and Scout classes to use `attr_accessor` instead of `instance_variable_set`/`instance_variable_get`
+- Extensive documentation updates across README, guides, API reference, and examples for front matter extras
+
+## [0.0.2] - 2026-02-15 (unreleased)
+
+### Added
+
+- **TypedBus message bus** for robot-to-robot communication
+  - `RobotMessage` immutable data class (`Data.define`) with `id`, `from`, `content`, `in_reply_to`
+  - Optional `bus:` parameter on Robot constructor — purely additive
+  - `on_message` handler with auto-ACK (1-arg block) and manual ACK/NACK (2-arg block)
+  - `publish_to_bus` with Async-aware fiber wrapping
+  - Typed channels accepting only `RobotMessage` objects
+- **Dynamic robot spawning** via `Robot#spawn` method for creating child robots at runtime
+- **`with_bus` configuration method** for connecting robots to a message bus after creation
+- **Comic robot class** with dynamic comedy tools (`reinvent_style`, `adjust_energy`, `get_coaching`)
+- New examples:
+  - `12_message_bus.rb` — two-robot joke critique workflow
+  - `13_spawn.rb` — dynamic robot spawning
+  - `14_rusty_circuit/` — multi-robot comedy open mic with bus-based coordination
+- New prompt templates: `comedian`, `comedy_critic`, `dispatcher`, `open_mic_comic`, `open_mic_heckler`, `open_mic_scout`, `configurable`, `llm_config_demo`
+- Rake tasks for building documentation sites
+- GitHub Actions workflow for YARD documentation deployment
+
+### Changed
+
+- Bumped version to 0.0.2
+- Replaced `ruby_llm-template` dependency with `prompt_manager` (~> 1.0)
+- Updated `ruby_llm` dependency to ~> 1.12
+- Added `typed_bus` as a core dependency
+- Added `myway_config` (~> 0.1) dependency
+- Added `amazing_print` and `hashdiff` as development dependencies
+- Migrated all prompt templates from directory-based format (`system.txt.erb` / `user.txt.erb`) to single `.md` files with YAML front matter
+- Refactored `Robot` class for simplified configuration
+- Refactored `Config` class
+- Extensive documentation updates across all guide, architecture, and API reference pages
+
+### Fixed
+
+- GitHub Actions platform limitation (`arm64-darwin` only in lockfile)
+
 ## [0.0.1] - 2026-01-16
 
 - refactored the network concept

data/README.md

@@ -18,8 +18,10 @@ RobotLab enables you to build sophisticated AI applications using multiple speci
 - <strong>Network Orchestration</strong> - Connect robots with flexible routing<br>
 - <strong>Extensible Tools</strong> - Give robots custom capabilities<br>
 - <strong>MCP Integration</strong> - Connect to external tool servers<br>
-- <strong>Shared Memory</strong> - Hierarchical memory with namespaced scopes<br>
+- <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
 - <strong>Conversation History</strong> - Persist and restore threads<br>
+- <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
+- <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
 - <strong>Streaming</strong> - Real-time event streaming<br>
 - <strong>Rails Integration</strong> - Generators and ActiveRecord support
 </td>
@@ -52,11 +54,6 @@ The simplest way to create a robot is with an inline `system_prompt`. This appro
 ```ruby
 require "robot_lab"
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.default_model = "claude-sonnet-4"
-end
-
 # Create a robot with an inline system prompt
 robot = RobotLab.build(
   name: "assistant",
@@ -64,66 +61,119 @@ robot = RobotLab.build(
 )
 
 # Run the robot
-result = robot.run(message: "What is the capital of France?")
+result = robot.run("What is the capital of France?")
 
-puts result.output.first.content
+puts result.last_text_content
 # => "The capital of France is Paris."
 ```
 
-### Using Templates
+### Configuration
 
-For production applications, RobotLab supports a powerful template system built on ERB. Templates allow you to:
+RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layered configuration. There is no `configure` block. Configuration is loaded automatically from multiple sources in priority order:
 
-- **Compose prompts** from reusable components
-- **Inject dynamic context** at build-time and run-time
-- **Version control** your prompts alongside your code
-- **Share prompts** across multiple robots
+1. Bundled defaults (`lib/robot_lab/config/defaults.yml`)
+2. Environment-specific overrides (development, test, production)
+3. XDG user config (`~/.config/robot_lab/config.yml`)
+4. Project config (`./config/robot_lab.yml`)
+5. Environment variables (`ROBOT_LAB_*` prefix)
 
-Configure the template directory:
+```bash
+# Set API keys via environment variables (double underscore for nesting)
+export ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+export ROBOT_LAB_RUBY_LLM__OPENAI_API_KEY=sk-...
+export ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
+```
 
 ```ruby
-RobotLab.configure do |config|
-  config.template_path = "app/prompts"
-end
+# Access configuration values
+RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+RobotLab.config.ruby_llm.request_timeout  #=> 120
+RobotLab.config.streaming_enabled         #=> true
 ```
 
-Each template is a **directory** containing ERB files for different message roles:
+Or create a project config file at `./config/robot_lab.yml`:
 
+```yaml
+ruby_llm:
+  model: claude-sonnet-4
+  anthropic_api_key: sk-ant-...
+  request_timeout: 180
 ```
-app/prompts/
-  assistant/
-    ├── system.txt.erb    # System message (required)
-    ├── user.txt.erb      # User prompt template (optional)
-    ├── assistant.txt.erb # Pre-filled assistant response (optional)
-    └── schema.rb         # Structured output schema (optional)
+
+### Using Templates
+
+For production applications, RobotLab supports a template system built on [PromptManager](https://github.com/MadBomber/prompt_manager). Templates allow you to:
+
+- **Compose prompts** from reusable Markdown files
+- **Inject dynamic context** at build-time
+- **Version control** your prompts alongside your code
+- **Share prompts** across multiple robots
+
+Each template is a `.md` file with YAML front matter for metadata and parameters:
+
+```
+prompts/
+  assistant.md
+  classifier.md
+  billing.md
 ```
 
-Create the system message at `app/prompts/assistant/system.txt.erb`:
+Create a template at `prompts/assistant.md`:
 
-```erb
+```markdown
+---
+description: A helpful assistant
+parameters:
+  company_name: null
+  tone: friendly
+---
 You are a helpful assistant for <%= company_name %>.
 
+Your communication style should be <%= tone %>.
+
 Your responsibilities:
 - Answer questions accurately and concisely
 - Be friendly and professional
 - Admit when you don't know something
-
-<% if guidelines %>
-Additional guidelines:
-<%= guidelines %>
-<% end %>
 ```
 
-Reference the template directory using a Symbol:
+Reference the template by symbol:
 
 ```ruby
 robot = RobotLab.build(
   name: "assistant",
   template: :assistant,
-  context: { company_name: "Acme Corp", guidelines: nil }
+  context: { company_name: "Acme Corp", tone: "professional" }
 )
 ```
 
+### Self-Contained Templates
+
+Templates can declare tools, MCP servers, name, and description in front matter, making the `.md` file a complete robot definition:
+
+```markdown
+---
+description: GitHub assistant with MCP tool access
+robot_name: github_bot
+tools:
+  - CodeSearchTool
+mcp:
+  - name: github
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+model: claude-sonnet-4
+---
+You are a GitHub assistant. Use available tools to help with repository tasks.
+```
+
+```ruby
+# Template provides everything — minimal constructor call
+robot = RobotLab.build(template: :github_assistant)
+```
+
+Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `parameters`, and LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`). Constructor-provided values always take precedence over front matter.
+
 ### Combining Templates with System Prompts
 
 The `system_prompt` parameter can also be used alongside a template. When both are provided, the template renders first and the `system_prompt` is appended. This is particularly useful during development and testing when you want to add temporary instructions or context to an existing template:
@@ -132,11 +182,76 @@ The `system_prompt` parameter can also be used alongside a template. When both a
 robot = RobotLab.build(
   name: "assistant",
   template: :assistant,
-  context: { company_name: "Acme Corp" },
+  context: { company_name: "Acme Corp", tone: "friendly" },
   system_prompt: "DEBUG MODE: Log all tool calls. Today's date is #{Date.today}."
 )
 ```
 
+### 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:
+
+```ruby
+robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer.")
+
+result = robot
+  .with_temperature(0.9)
+  .with_model("claude-sonnet-4")
+  .with_max_tokens(2000)
+  .run("Write a haiku about Ruby programming")
+```
+
 ## Creating a Robot with Tools
 
 ```ruby
@@ -163,14 +278,14 @@ class Magic8Ball < RubyLLM::Tool
   end
 end
 
-# Create robot with tools
+# Create robot with tools via local_tools: parameter
 robot = RobotLab.build(
   name: "oracle",
   system_prompt: "You are a mystical oracle. Use the Magic 8-Ball to answer questions about the future.",
-  tools: [Magic8Ball]
+  local_tools: [Magic8Ball]
 )
 
-result = robot.run(message: "Should I start learning Rust?")
+result = robot.run("Should I start learning Rust?")
 ```
 
 ## Orchestrating Multiple Robots
@@ -181,7 +296,10 @@ Networks use [SimpleFlow](https://github.com/MadBomber/simple_flow) pipelines wi
 # Custom classifier that activates the appropriate specialist
 class ClassifierRobot < RobotLab::Robot
   def call(result)
-    robot_result = run(**extract_run_context(result))
+    context = extract_run_context(result)
+    message = context.delete(:message)
+
+    robot_result = run(message, **context)
 
     new_result = result
       .with_context(@name.to_sym, robot_result)
@@ -228,15 +346,15 @@ Both robots and networks have inherent memory that persists across runs:
 # Standalone robot with inherent memory
 robot = RobotLab.build(name: "assistant", system_prompt: "You are helpful.")
 
-robot.run(message: "My name is Alice")
-robot.run(message: "What's my name?")  # Memory persists automatically
+robot.run("My name is Alice")
+robot.run("What's my name?")  # Memory persists automatically
 
 # Access robot's memory
 robot.memory[:user_id] = 123
 robot.memory.data[:category] = "billing"
 
 # Runtime memory injection
-robot.run(message: "Help me", memory: { session_id: "abc123", tier: "premium" })
+robot.run("Help me", memory: { session_id: "abc123", tier: "premium" })
 
 # Reset memory when needed
 robot.reset_memory
@@ -285,26 +403,123 @@ filesystem_server = {
 robot = RobotLab.build(
   name: "developer",
   template: :developer,
-  mcp_servers: [filesystem_server]
+  mcp: [filesystem_server]
 )
 
 # Robot can now use filesystem tools
-result = robot.run(message: "List the files in the current directory")
+result = robot.run("List the files in the current directory")
+```
+
+## Message Bus
+
+Robots can communicate bidirectionally via an optional message bus, independent of the Network pipeline. This enables negotiation loops, convergence patterns, and cyclic workflows.
+
+Connect robots to a bus at construction time with `bus:`, or after creation with `with_bus`:
+
+```ruby
+require "robot_lab"
+
+bus = TypedBus::MessageBus.new
+
+class Comedian < RobotLab::Robot
+  def initialize(bus:)
+    super(name: "bob", template: :comedian, bus: bus)
+    on_message do |message|
+      joke = run(message.content.to_s).last_text_content.strip
+      send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
+    end
+  end
+end
+
+class ComedyCritic < RobotLab::Robot
+  def initialize(bus:)
+    super(name: "alice", template: :comedy_critic, bus: bus)
+    @accepted = false
+    on_message do |message|
+      verdict = run("Evaluate this joke:\n\n#{message.content}").last_text_content.strip
+      @accepted = verdict.start_with?("FUNNY")
+      send_message(to: :bob, content: "Try again.") unless @accepted
+    end
+  end
+  attr_reader :accepted
+end
+
+bob   = Comedian.new(bus: bus)
+alice = ComedyCritic.new(bus: bus)
+alice.send_message(to: :bob, content: "Tell me a funny robot joke.")
 ```
 
+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** — `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
+
+## Dynamic Robot Spawning
+
+Robots can create new robots at runtime using `spawn`. The bus is created lazily — no upfront wiring required:
+
+```ruby
+require "robot_lab"
+
+class Dispatcher < RobotLab::Robot
+  attr_reader :spawned
+
+  def initialize(bus: nil)
+    super(name: "dispatcher", system_prompt: "Decide which specialist to create.", bus: bus)
+    @spawned = {}
+
+    on_message do |message|
+      puts "Got reply from #{message.from}: #{message.content.to_s.lines.first&.strip}"
+    end
+  end
+
+  def dispatch(question)
+    # Spawn a specialist (reuse if already spawned)
+    specialist = @spawned["helper"] ||= spawn(
+      name: "helper",
+      system_prompt: "You answer questions concisely."
+    )
+
+    # Have the specialist work and reply
+    answer = specialist.run(question).last_text_content.strip
+    specialist.send_message(to: :dispatcher, content: answer)
+  end
+end
+
+dispatcher = Dispatcher.new
+dispatcher.dispatch("What is the capital of France?")
+```
+
+Key features:
+
+- **`spawn`** — creates a child robot on the same bus; creates a bus lazily if none exists
+- **`with_bus`** — connect a robot to a bus after creation (`bot.with_bus(existing_bus)`)
+- **Fan-out** — multiple robots with the same name all receive messages sent to that name
+- **No setup required** — bus and channels are created automatically on first use
+
 ## Streaming
 
-Subscribe to real-time events during execution:
+Use a `Streaming::Context` with a publish callback to receive real-time events:
 
 ```ruby
-result = robot.run(message: "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