robot_lab 0.0.1 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a73bb0d9c45aa5f2f904e744774ecb3396027fa17a7c099a1ede7ac57598929
-  data.tar.gz: 8ff58ce299752cb0ff12365637070d71f35b011613a62b01a62d2fe43523a87c
+  metadata.gz: 8d3bfa06c07301b03b01359a15a945374b135f2055c77396ad456a916917a742
+  data.tar.gz: 0b9e81d50841bf9a56d4efcc8f4175f34aa0e17702c89cc4bd5d4750631c0f68
 SHA512:
-  metadata.gz: afa598bbaea859d6f70f6bef21c936fc4f6260cf15c8af786dbaee5ce4d71c4d24e9f4e63a243e9a3321d2659f04cd6fab86f19568852b3cbd659eb9f4b339a1
-  data.tar.gz: 77ea74d0251124766263e3baf64f80889a56ecffa248a1ac612cd0ea1ea495ee090a3830a575090fb5f13dfac55d3c10a0097c182f57cc5a47c3167b5cb4e29f
+  metadata.gz: 15649fd320dd84530d49884900d99c2cdc98ddd5841948b052ed6b3a6f3d0fa9cec3e80636883f6d2bcd5b5a8ffe6b61ad681dc907faf5e881f48ac05ebef0fd
+  data.tar.gz: cdd136aad382247babb5639cf3a2b0b35db5086b33661823a6e00d8099f2a18a57325c3ed57f3474d23ee8f317f65c1f0b70911d349ad04f111d80cac03dd8c9

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,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+```
+
+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
 ```
 
-Each template is a **directory** containing ERB files for different message roles:
+### 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:
 
 ```
-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)
+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,25 @@ 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}."
 )
 ```
 
+### 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 +227,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 +245,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 +295,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,19 +352,109 @@ 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
+      reply(message, joke)
+    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** — `reply(message, content)` tracks conversation threads via `in_reply_to`
+- **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:
+Pass a block to `run` to receive real-time events during execution:
 
 ```ruby
-result = robot.run(message: "Tell me a story") do |event|
+result = robot.run("Tell me a story") do |event|
   case event[:event]
   when "text.delta"
     print event[:data][:delta]

data/Rakefile

@@ -45,23 +45,92 @@ task :rubocop_fix do
 end
 
 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"
+  }.freeze
+
   desc "Run all examples"
   task :all do
+    # Single-file examples
     Dir.glob("examples/*.rb").sort.each do |example|
       puts "\n#{'=' * 60}"
       puts "Running: #{example}"
       puts '=' * 60
       ruby example
     end
+
+    # Subdirectory-based demos
+    SUBDIR_ENTRY_POINTS.each do |dir, entry|
+      path = "examples/#{dir}/#{entry}"
+      next unless File.exist?(path)
+
+      puts "\n#{'=' * 60}"
+      puts "Running: #{path}"
+      puts '=' * 60
+      ruby path
+    end
   end
 
   desc "Run a specific example by number (e.g., rake examples:run[1])"
   task :run, [:num] do |_t, args|
-    example = Dir.glob("examples/#{args[:num].rjust(2, '0')}_*.rb").first
+    padded = args[:num].rjust(2, '0')
+
+    # Try single-file example first
+    example = Dir.glob("examples/#{padded}_*.rb").first
     if example
       ruby example
+      next
+    end
+
+    # Try subdirectory-based demo
+    dir = Dir.glob("examples/#{padded}_*/").first
+    if dir
+      dir_name = File.basename(dir)
+      entry = SUBDIR_ENTRY_POINTS[dir_name]
+      if entry && File.exist?(File.join(dir, entry))
+        ruby File.join(dir, entry)
+      else
+        puts "Example #{args[:num]} directory found (#{dir_name}) but no entry point configured"
+      end
     else
       puts "Example #{args[:num]} not found"
     end
   end
 end
+
+namespace :docs do
+  desc "Build all documentation (YARD and MkDocs)"
+  task build: %i[yard mkdocs]
+
+  desc "Clean generated documentation"
+  task :clean do
+    rm_rf "doc"
+    rm_rf "site"
+  end
+
+  desc "Build YARD API documentation"
+  task :yard do
+    sh "yard doc"
+  end
+
+  namespace :yard do
+    desc "Serve YARD documentation locally"
+    task :serve do
+      sh "yard server --reload"
+    end
+  end
+
+  desc "Build MkDocs documentation"
+  task :mkdocs do
+    sh "mkdocs build"
+  end
+
+  namespace :mkdocs do
+    desc "Serve MkDocs documentation locally"
+    task :serve do
+      sh "mkdocs serve"
+    end
+  end
+end

data/docs/api/core/index.md

@@ -43,10 +43,20 @@ classDiagram
         +scoped(namespace)
     }
 
+    class RobotMessage {
+        +id: Integer
+        +from: String
+        +content: String
+        +in_reply_to: String
+        +key()
+        +reply?()
+    }
+
     Network --> Robot : contains
     Robot --> Tool : has
     State --> Memory : has
     Network --> State : uses
+    Robot ..> RobotMessage : sends/receives
 ```
 
 ## Classes
@@ -57,7 +67,9 @@ classDiagram
 | [Network](network.md) | Container for robots with routing and orchestration |
 | [State](state.md) | Conversation state with data, results, and memory |
 | [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 |
+| RobotMessage | Typed envelope for bus-based inter-robot communication |
 
 ## Quick Examples