robot_lab 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de87b78206bc424703b465d3a1f236db723ea38fe4235c07413466ab5b469ead
-  data.tar.gz: 6a7db14e4530e615e258415491422f297567a2f640983035f1542d88e7d200e5
+  metadata.gz: 411c496dec788609f2ac0d2e1eb02ce7fd0523f40424b9437de0ffb24c00c644
+  data.tar.gz: 9fb9bb55b865734dc7c9ae1ac8d1994685575c1ee206d6cf9865c0af3d3a522c
 SHA512:
-  metadata.gz: f6814c9a8b86b8e6d1df2adcc2d9b4ab84c176c67211424e8404e9d83c1e08ffd353587523e4c45efec295d0e47bbd731b0cdc6f3e62754cfd4f1ce2a33d7655
-  data.tar.gz: 37682af098203ae333cc83fa6e66a95f1883aae0bed8411524a05d6795bb47b4a99f231353fe3546b2fdae8a5c098d0f45b863e531edaf237aab33e4e1bc3859
+  metadata.gz: b34ce72ebe6443c5f25423a595c0ffd468416ea1be02531b125efed33289ae8ea898c5413697fe373cebd658bddb510f322ef09623bb7b74f7587cf58b9ad064
+  data.tar.gz: e9884f0c8b501bfc57eafdc6c5492fea7455eb807267c370fc68b59e7322f97c0360e3af6f7e61b7c2493df3e2026f72095b9c287e65e6bf5f1ec5274948ef7d

data/.envrc

@@ -2,5 +2,5 @@
 
 source_up
 
-export RR=`pwd`
-export BUNDLE_GEMFILE=Gemfile
+export RR=$(pwd)
+# BUNDLE_GEMFILE is inherited from the project root .envrc (asgard dev|prod)

data/CHANGELOG.md

@@ -6,6 +6,59 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.3.0] - 2026-09-18
+
+The ruby_llm 2.0 release. Core moves from ruby_llm 1.x to the official 2.0.0
+release; every `robot_lab-*` extension gem releases in lockstep at 0.3.0 and
+now requires `robot_lab ~> 0.3.0`.
+
+### Changed (BREAKING)
+- **ruby_llm 1.x → 2.0.** The gemspec now requires `ruby_llm "~> 2.0"`
+  (official release). Robot tools written with the 1.x DSL must migrate:
+  `param` → `parameter`, `desc:` → `description:`; `halt` is gone (the caller
+  controls the loop). Token counts moved to `response.tokens.input/.output`,
+  and `finish_reason` (Symbol) replaces `stop_reason`. The `claude-sonnet-4`
+  registry alias no longer resolves; the default models are now
+  `claude-sonnet-4-6` (production) and `claude-haiku-4-5` (test).
+- **Dropped hard dependencies** on `ruby_llm-mcp`, `ruby_llm-schema`, and
+  `ruby_llm-semantic_cache`. Semantic caching is now optional: `Memory#cache`
+  returns `nil` when `ruby_llm-semantic_cache` is not installed and Memory
+  runs with caching disabled. (Its released versions still pin ruby_llm 1.x,
+  so it cannot co-resolve with 2.0 yet.)
+
+### Added
+- `ruby_llm-providers-apfel` and `ruby_llm-providers-lms` (`~> 0.2.1`) as
+  runtime dependencies, consumed as released gems — the local `path:`
+  overrides for sibling checkouts are gone from the Gemfiles.
+- `Robot::ResultBuilding` — extracted module that adapts a ruby_llm response
+  into a `RobotResult` (token accounting, stop-reason normalization, message
+  coercion).
+- `examples/run_all.rb` — runs every executable `NN_*.rb` demo serially with
+  a banner between each; works from any cwd, and Ctrl-C terminates only the
+  demo currently running (the runner notes it and moves on).
+- READMEs for the subdirectory demos: `15_memory_network_and_bus`,
+  `26_document_store` (corpus), and `27_incident_response`.
+- Fasterer quality gate now actually runs: `fasterer` added to the
+  development group, with a `.fasterer.yml` documenting the disabled
+  speed-over-readability checks.
+
+### Changed
+- Robot, Tool, RunConfig, and the hook system adapted to the ruby_llm 2.0
+  API; docs and examples synced to match.
+- Examples run against a local LM Studio server through the `:lms` provider;
+  `examples/common.rb` anchors `BUNDLE_GEMFILE` to the gem root so demos run
+  from any directory, and `examples/README.md` notes that demo speed and
+  answer quality depend on the provider/model in use.
+- `.envrc` no longer exports `BUNDLE_GEMFILE`; it is inherited from the
+  project root (`asgard dev` / `asgard prod`).
+
+### Fixed
+- amazing_print 3.0 crash at demo startup (`undefined method 'try' for
+  module ActiveSupport`): robot_lab's dependencies load parts of
+  ActiveSupport, which tricked amazing_print into loading its Rails
+  extension; `examples/common.rb` now preloads
+  `active_support/core_ext/object/try` and `active_support/log_subscriber`.
+
 ## [0.2.8] - 2026-09-09
 
 ### Added

data/CLAUDE.md

@@ -55,7 +55,7 @@ bundle exec rake examples:run[1]
 
 ### Memory System
 
-- **`Memory`** (`lib/robot_lab/memory.rb`): Key-value store with reserved keys (`:data`, `:results`, `:messages`, `:session_id`, `:cache`). Supports Redis backend. Includes semantic caching via RubyLLM::SemanticCache
+- **`Memory`** (`lib/robot_lab/memory.rb`): Key-value store with reserved keys (`:data`, `:results`, `:messages`, `:session_id`, `:cache`). Supports Redis backend. Semantic caching via RubyLLM::SemanticCache when the optional ruby_llm-semantic_cache gem is installed (`memory.cache` is nil otherwise)
 
 ### MCP (Model Context Protocol)
 
@@ -119,7 +119,9 @@ Router receives `Router::Args` with: `context`, `network`, `stack`, `call_count`
 
 ## Dependencies
 
-Core: zeitwerk, ruby_llm (~> 1.12), ruby_llm-mcp, prompt_manager, ruby_llm-schema, ruby_llm-semantic_cache, async, simple_flow, state_machines
+Core: zeitwerk, ruby_llm (~> 2.0.0.rc3), prompt_manager, async, simple_flow, state_machines
+
+Optional: ruby_llm-semantic_cache (Memory#cache; no ruby_llm 2.0-compatible release yet — Memory runs with caching disabled when absent), classifier (compress_history), ruby_llm-providers-lms (local LM Studio provider used by the examples: qwen/qwen3.8-27b for complex work, openai/gpt-oss-20b for simple demos)
 
 ### Templates
 

data/README.md

@@ -21,7 +21,7 @@
 - <strong>Human-in-the-Loop</strong> - AskUser tool for interactive prompting<br>
 - <strong>Content Streaming</strong> - Stored callbacks, per-call blocks, or both<br>
 - <strong>MCP Integration</strong> - Connect to external tool servers with timeouts and retry<br>
-- <strong>Local LLM Providers</strong> - Ollama and GPUStack via provider passthrough<br>
+- <strong>Local LLM Providers</strong> - LM Studio (via ruby_llm-providers-lms), Ollama, and GPUStack via provider passthrough<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
@@ -82,17 +82,15 @@ puts result.last_text_content
 
 ### Local LLM Providers
 
-For local LLM providers, use the `provider:` parameter. RubyLLM's provider list is the authority on valid values — `:ollama` and `:gpustack` are the local ones (alongside `:anthropic`, `:azure`, `:bedrock`, `:deepseek`, `:gemini`, `:mistral`, `:openai`, `:openrouter`, `:perplexity`, `:vertexai`, and `:xai`). The provider's API base must be configured first, or building the robot raises `RubyLLM::ConfigurationError`:
-
-```bash
-export ROBOT_LAB_RUBY_LLM__OLLAMA_API_BASE=http://localhost:11434/v1
-```
+For local LLM providers, use the `provider:` parameter. RubyLLM's provider list is the authority on valid values — `:ollama` and `:gpustack` are built in, and provider gems add more (alongside `:anthropic`, `:azure`, `:bedrock`, `:deepseek`, `:gemini`, `:mistral`, `:openai`, `:openrouter`, `:perplexity`, `:vertexai`, and `:xai`). The examples in this repo use LM Studio through the [ruby_llm-providers-lms](https://github.com/madbomber/ruby_llm-providers-lms) gem, which registers the `:lms` provider (defaults to `http://localhost:1234/v1`, no API key needed):
 
 ```ruby
+require "ruby_llm/providers/lms"
+
 robot = RobotLab.build(
   name: "local_bot",
-  model: "llama3.2",
-  provider: :ollama,
+  model: "qwen/qwen3.8-27b",   # complex work; use "openai/gpt-oss-20b" for simple chat
+  provider: :lms,
   system_prompt: "You are a helpful assistant."
 )
 ```
@@ -113,12 +111,12 @@ RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layer
 # 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
+export ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4-6
 ```
 
 ```ruby
 # Access configuration values
-RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4-6"
 RobotLab.config.ruby_llm.request_timeout  #=> 120
 ```
 
@@ -126,7 +124,7 @@ Or create a project config file at `./config/robot_lab.yml`:
 
 ```yaml
 ruby_llm:
-  model: claude-sonnet-4
+  model: claude-sonnet-4-6
   anthropic_api_key: sk-ant-...
   request_timeout: 180
 ```
@@ -202,7 +200,7 @@ mcp:
       type: stdio
       command: npx
       args: ["-y", "@modelcontextprotocol/server-github"]
-model: claude-sonnet-4
+model: claude-sonnet-4-6
 ---
 You are a GitHub assistant. Use available tools to help with repository tasks.
 ```
@@ -265,7 +263,7 @@ robot = RobotLab.build(
 ```ruby
 # Create a shared config
 shared = RobotLab::RunConfig.new(
-  model: "claude-sonnet-4",
+  model: "claude-sonnet-4-6",
   temperature: 0.7,
   max_tokens: 2000
 )
@@ -302,16 +300,16 @@ RunConfig supports keyword construction, block DSL, and merge semantics:
 ```ruby
 # Block DSL
 config = RobotLab::RunConfig.new do |c|
-  c.model "claude-sonnet-4"
+  c.model "claude-sonnet-4-6"
   c.temperature 0.7
 end
 
 # Merge (more-specific wins)
-network_config = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+network_config = RobotLab::RunConfig.new(model: "claude-sonnet-4-6", 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"
+effective.model        #=> "claude-sonnet-4-6"
 ```
 
 ### Chaining Configuration
@@ -323,7 +321,7 @@ robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer
 
 result = robot
   .with_temperature(0.9)
-  .with_model("claude-sonnet-4")
+  .with_model("claude-sonnet-4-6")
   .run("Write a haiku about Ruby programming")
 ```
 

data/docs/architecture/core-concepts.md

@@ -226,7 +226,7 @@ end
 | `:results` | `Array` | Accumulated robot results |
 | `:messages` | `Array` | Conversation history |
 | `:session_id` | `String` | Session identifier |
-| `:cache` | `Module` | Semantic cache (RubyLLM::SemanticCache) |
+| `:cache` | `Module`, `nil` | Semantic cache (RubyLLM::SemanticCache when the optional gem is installed) |
 
 ### Reactive Features
 

data/docs/architecture/state-management.md

@@ -13,7 +13,7 @@ memory.data        # StateProxy - custom key-value data with method-style access
 memory.results     # Array<RobotResult> - execution history
 memory.messages    # Array<Message> - conversation history
 memory.session_id  # String - optional persistence identifier
-memory.cache       # RubyLLM::SemanticCache - semantic caching module
+memory.cache       # RubyLLM::SemanticCache when the optional gem is installed, else nil
 ```
 
 ## Standalone Robot Memory
@@ -108,7 +108,7 @@ Memory has five reserved keys with special behavior and dedicated accessors:
 | `:results` | `Array<RobotResult>` | Accumulated robot execution results |
 | `:messages` | `Array<Message>` | Conversation history |
 | `:session_id` | `String` | Conversation session identifier |
-| `:cache` | `RubyLLM::SemanticCache` | Semantic cache module (read-only after init) |
+| `:cache` | `RubyLLM::SemanticCache` or `nil` | Semantic cache module when the optional ruby_llm-semantic_cache gem is installed (read-only after init) |
 
 Reserved keys are accessed through dedicated methods and are excluded from `memory.keys`:
 
@@ -118,7 +118,7 @@ memory.data.category  #=> "billing"   (method-style via StateProxy)
 
 memory.results       #=> []
 memory.session_id    #=> nil
-memory.cache         #=> RubyLLM::SemanticCache (the module itself), or nil when enable_cache: false
+memory.cache         #=> RubyLLM::SemanticCache (the module itself), or nil when enable_cache: false or the optional gem is absent
 ```
 
 ## StateProxy
@@ -319,7 +319,7 @@ memory = Memory.from_hash(hash)
 
 ## Semantic Cache
 
-Memory includes a semantic cache via `RubyLLM::SemanticCache` that reduces costs and latency by returning cached responses for semantically equivalent queries:
+Memory includes a semantic cache via `RubyLLM::SemanticCache` (optional ruby_llm-semantic_cache gem; not yet ruby_llm 2.0-compatible, so `memory.cache` is `nil` without it) that reduces costs and latency by returning cached responses for semantically equivalent queries:
 
 ```ruby
 # Using the cache with fetch

data/docs/concepts.md

@@ -338,7 +338,7 @@ robot.clear_messages(keep_system: true)
 | `:results` | Accumulated robot results |
 | `:messages` | Conversation history |
 | `:session_id` | Session identifier for history persistence |
-| `:cache` | Semantic cache instance (RubyLLM::SemanticCache) |
+| `:cache` | Semantic cache (RubyLLM::SemanticCache when the optional gem is installed, else nil) |
 
 ### Reactive Memory in Networks
 

data/docs/getting-started/installation.md

@@ -35,13 +35,10 @@ RobotLab automatically installs these core dependencies:
 
 | Gem | Purpose |
 |-----|---------|
-| `ruby_llm` (~> 1.12) | LLM provider integrations (Anthropic, OpenAI, Gemini, etc.) |
+| `ruby_llm` (~> 2.0.0.rc3) | LLM provider integrations (Anthropic, OpenAI, Gemini, etc.) |
 | `prompt_manager` (~> 1.0) | Template-based prompt management with YAML front matter |
 | `simple_flow` (~> 0.4) | Pipeline workflow execution for networks |
 | `myway_config` (~> 0.1) | Layered configuration (defaults, env vars, config files) |
-| `ruby_llm-mcp` (~> 1.0) | Model Context Protocol client for external tool servers |
-| `ruby_llm-schema` (~> 0.3) | Schema validation for structured outputs |
-| `ruby_llm-semantic_cache` (~> 0.1) | Semantic caching for LLM responses |
 | `zeitwerk` (~> 2.6) | Autoloading and eager loading |
 | `async` (~> 2.0) | Fiber-based concurrency |
 | `async-http` (~> 0.60) | MCP SSE and streamable-HTTP transports |

data/docs/guides/memory.md

@@ -10,7 +10,7 @@ Memory is a reactive key-value store that provides:
 - Reserved keys for structured data (`:data`, `:results`, `:messages`, `:session_id`, `:cache`)
 - Reactive subscriptions and blocking reads for inter-robot communication
 - Optional Redis backend for persistence
-- Semantic caching via `RubyLLM::SemanticCache`
+- Semantic caching via `RubyLLM::SemanticCache` (optional ruby_llm-semantic_cache gem)
 
 ## Standalone Robot Memory
 
@@ -86,7 +86,7 @@ Memory has reserved keys with special behavior:
 | `:results` | Array | Accumulated robot results |
 | `:messages` | Array | Conversation history |
 | `:session_id` | String | Session identifier for history persistence |
-| `:cache` | `RubyLLM::SemanticCache` module, or `nil` | Semantic cache (read-only after init). Set at construction time; `nil` when built with `enable_cache: false` |
+| `:cache` | `RubyLLM::SemanticCache` module, or `nil` | Semantic cache (read-only after init). Set at construction time; `nil` when built with `enable_cache: false` or when the optional gem is absent |
 
 ### The Data Hash
 

data/examples/.envrc

@@ -1 +1,3 @@
+source_up
+
 export ROBOT_LAB_TEMPLATE_PATH="${PWD}/prompts"

data/examples/02_tools.rb

@@ -14,17 +14,17 @@ require_relative "common"
 class Calculator < RubyLLM::Tool
   description "Performs basic arithmetic operations"
 
-  param :operation,
+  parameter :operation,
         type: "string",
-        desc: "The operation to perform (add, subtract, multiply, divide)"
+        description: "The operation to perform (add, subtract, multiply, divide)"
 
-  param :a,
+  parameter :a,
         type: "number",
-        desc: "First operand"
+        description: "First operand"
 
-  param :b,
+  parameter :b,
         type: "number",
-        desc: "Second operand"
+        description: "Second operand"
 
   def execute(operation:, a:, b:)
     case operation
@@ -40,9 +40,9 @@ end
 class FortuneCookie < RubyLLM::Tool
   description "Get a fortune cookie message with wisdom and lucky numbers"
 
-  param :category,
+  parameter :category,
         type: "string",
-        desc: "The category of fortune (wisdom, love, career, adventure)"
+        description: "The category of fortune (wisdom, love, career, adventure)"
 
   FORTUNES = {
     "wisdom" => [

data/examples/03_network.rb

@@ -40,7 +40,7 @@ end
 
 # Shared RunConfig — operational defaults every robot in this network inherits.
 #
-# RunConfig has no `provider` field (see RunConfig::FIELDS), and an Ollama
+# RunConfig has no `provider` field (see RunConfig::FIELDS), and an LM Studio
 # model is absent from RubyLLM's registry, so provider and model still travel
 # together on each robot via **llm_opts. The RunConfig carries the settings
 # that genuinely are shared.

data/examples/04_mcp.rb

@@ -163,14 +163,16 @@ begin
   puts "Query: 'What are the top 3 most starred Ruby web frameworks on GitHub?'"
   hr
 
-  # mcp: :inherit and tools: :inherit are both required. Both keywords default
-  # to :none on run(), which resolves to "no MCP servers this turn" and "send
-  # zero tools this turn" — the discovered MCP tools would never reach the
-  # provider and the model would answer from its training data.
+  # mcp: :inherit is required — run() defaults it to :none, which resolves to
+  # "no MCP servers this turn" and the discovered tools would never reach the
+  # provider. tools: takes an allowlist of tool names; :inherit would send all
+  # ~90 GitHub tools, whose JSON schemas alone exceed 13k tokens and overflow
+  # a local model's context window (LM Studio's default is 8192) before the
+  # query even arrives. Send only the one tool this query needs.
   result = robot.run(
     "What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.",
     mcp:   :inherit,
-    tools: :inherit
+    tools: %w[search_repositories]
   )
 
   puts

data/examples/08_llm_config.rb

@@ -20,9 +20,9 @@
 # Environment is determined by ROBOT_LAB_ENV, RAILS_ENV, or RACK_ENV.
 #
 # Environment variable examples:
-#   ROBOT_LAB_RUBY_LLM__MODEL=qwen3.6:latest
+#   ROBOT_LAB_RUBY_LLM__MODEL=qwen/qwen3.8-27b
 #   ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=180
-#   OLLAMA_API_BASE=http://localhost:11434/v1
+#   LMS_API_BASE=http://localhost:1234/v1
 #
 # Usage:
 #   ruby examples/08_llm_config.rb
@@ -63,7 +63,7 @@ puts "  max_retries:        #{config.ruby_llm.max_retries}"
 puts "  log_level:          #{config.ruby_llm.log_level}"
 
 # Show where the LLM traffic actually goes
-puts "  ollama_api_base:    #{OLLAMA_API_BASE}"
+puts "  lms_api_base:       #{LMS_API_BASE}"
 puts "  (local inference — no API key in play)"
 puts
 
@@ -92,7 +92,7 @@ shared = RobotLab::RunConfig.new(model: LLM[:default].model, temperature: 0.5)
 puts "  shared = RunConfig.new(model: #{LLM[:default].model.inspect}, temperature: 0.5)"
 puts "  shared.to_h => #{shared.to_h.inspect}"
 puts
-puts "  Note: RunConfig carries no `provider` field, so an Ollama model still"
+puts "  Note: RunConfig carries no `provider` field, so an LM Studio model still"
 puts "  needs provider: passed to each robot alongside the shared config."
 puts
 
@@ -153,7 +153,7 @@ puts <<~FOOTER
   Example environment variable overrides:
     ROBOT_LAB_RUBY_LLM__MODEL=#{LLM[:default].model}
     ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=180
-    OLLAMA_API_BASE=http://localhost:11434/v1
+    LMS_API_BASE=http://localhost:1234/v1
 
   Try running with different environments:
     ROBOT_LAB_ENV=test ruby examples/08_llm_config.rb

data/examples/09_chaining.rb

@@ -233,9 +233,9 @@ interactive.output = output
 interactive.input  = StringIO.new("2\n")
 
 result = demo_tool.call(
-  "question" => "What type of task should I optimize for?",
-  "choices"  => %w[general analysis creative coding research],
-  "default"  => "general"
+  question: "What type of task should I optimize for?",
+  choices:  %w[general analysis creative coding research],
+  default:  "general"
 )
 
 puts output.string

data/examples/14_rusty_circuit/comic.rb

@@ -11,8 +11,8 @@ class ReinventStyle < RobotLab::Tool
               "Be bold — try something totally different. " \
               "The new style takes effect on your next bit."
 
-  param :new_persona, type: "string",
-        desc: "Your new comedy persona, style, and approach. " \
+  parameter :new_persona, type: "string",
+        description: "Your new comedy persona, style, and approach. " \
               "Be specific: what kind of humor, what voice, what attitude."
 
   def execute(new_persona:)
@@ -29,10 +29,10 @@ class AdjustEnergy < RobotLab::Tool
               "Higher (0.8-1.0) = wilder, riskier, more unpredictable. " \
               "Lower (0.2-0.4) = tighter, more controlled, precise."
 
-  param :level, type: "number",
-        desc: "Energy level from 0.1 (very controlled) to 1.0 (unhinged)"
-  param :reason, type: "string",
-        desc: "Why you're adjusting", required: false
+  parameter :level, type: "number",
+        description: "Energy level from 0.1 (very controlled) to 1.0 (unhinged)"
+  parameter :reason, type: "string",
+        description: "Why you're adjusting", required: false
 
   def execute(level:, reason: "tactical adjustment")
     clamped = [[level.to_f, 0.1].max, 1.0].min
@@ -47,8 +47,8 @@ class GetCoaching < RobotLab::Tool
               "Use when you're struggling with the crowd and need " \
               "an outside perspective on what to try next."
 
-  param :situation, type: "string",
-        desc: "Describe what's happening and what you need help with"
+  parameter :situation, type: "string",
+        description: "Describe what's happening and what you need help with"
 
   def execute(situation:)
     @coaches ||= {}

data/examples/14_rusty_circuit/scout.rb

@@ -10,8 +10,8 @@ class RecruitAnalyst < RobotLab::Tool
               "of the comedian's performance. The analyst will " \
               "review your accumulated notes and provide insight."
 
-  param :specialty, type: "string",
-        desc: "What to analyze: timing, crowd_work, " \
+  parameter :specialty, type: "string",
+        description: "What to analyze: timing, crowd_work, " \
               "originality, adaptability, stage_presence, " \
               "material_evolution"
 
@@ -46,8 +46,8 @@ class RefineCriteria < RobotLab::Tool
               "important qualities aren't what you initially expected. " \
               "The update takes effect on your next evaluation."
 
-  param :updated_criteria, type: "string",
-        desc: "Your refined evaluation criteria and focus areas"
+  parameter :updated_criteria, type: "string",
+        description: "Your refined evaluation criteria and focus areas"
 
   def execute(updated_criteria:)
     robot.pending_criteria = updated_criteria

data/examples/15_memory_network_and_bus/README.md

@@ -0,0 +1,66 @@
+# Example 15: OS Research Editorial Pipeline
+
+A multi-robot editorial pipeline that showcases RobotLab's three coordination
+mechanisms — **Network**, **Memory**, and **Bus** — plus dynamic robot
+creation with **spawn()**, all in one demo.
+
+## What it does
+
+Three writer robots each advocate for a different operating system (macOS,
+Windows, Linux/BSD) as the base for a home AI research lab:
+
+1. **Phase 1 — Writing pipeline (Network + Memory + Spawn).** The network runs
+   the three writers in parallel; each stores its draft in shared memory
+   (`:mac_draft`, `:windows_draft`, `:linux_draft`). The Linux writer first
+   `spawn()`s distro specialists and folds their analyses into its draft. An
+   editor robot then synthesizes the drafts into one combined article.
+2. **Phase 2 — Editorial review (Bus).** An editor-in-chief robot lives
+   *outside* the network and talks to the editor only over the message bus.
+   It reviews the article and replies `APPROVED` or `REVISE: <feedback>`,
+   looping until approval or `MAX_REVISIONS` (3) is reached.
+
+The demo is lightly interactive: at startup an `AskUser` prompt asks for the
+article's research focus. Press Enter to accept the default ("LLM
+fine-tuning, image generation, and local inference").
+
+## How to run
+
+From the gem root (an LM Studio server must be running — `lms server start`;
+see `examples/common.rb` for the provider/model configuration):
+
+```bash
+bundle exec ruby examples/15_memory_network_and_bus/editorial_pipeline.rb
+```
+
+Note that `examples/run_all.rb` does **not** include this demo — it only runs
+the top-level `NN_*.rb` files, so run it explicitly as above.
+
+This is one of the heavier examples (roughly 20-30 LLM calls). On the default
+model expect a long run; `LLM_PROFILE=small` trades answer quality for a much
+shorter one:
+
+```bash
+LLM_PROFILE=small bundle exec ruby examples/15_memory_network_and_bus/editorial_pipeline.rb
+```
+
+## Output
+
+Everything lands in `output/`:
+
+| File | Content |
+|------|---------|
+| `mac_draft.md`, `windows_draft.md`, `linux_draft.md` | each writer's advocacy draft |
+| `combined_article.md` | the editor's synthesis of the three drafts |
+| `revision_N.md` | one file per bus-driven revision round |
+| `final_article.md` | the approved article (header notes APPROVED or NOT APPROVED) |
+| `memory.json` | dump of the shared memory at the end of the run |
+
+## Files
+
+- `editorial_pipeline.rb` — entry point; builds the robots, network, and bus, then runs both phases
+- `os_writer.rb` — base writer; runs the LLM and stores its draft in shared memory
+- `linux_writer.rb` — extends `OsWriter`; spawns distro specialists before drafting
+- `os_editor.rb` — synthesizes drafts; handles revision requests from the bus
+- `editor_in_chief.rb` — bus-only reviewer; approves or requests revisions
+- `prompts/` — templates for the writers (`os_advocate.md`), editor, and chief
+- `.envrc` — sets `ROBOT_LAB_TEMPLATE_PATH` to `prompts/` for direnv users (the script sets the same fallback itself, so direnv is optional)

data/examples/15_memory_network_and_bus/output/combined_article.md

@@ -1,13 +1,11 @@
 # Combined Article (Editor Draft)
 
-For a home AI research lab, the operating-system decision is less about ideology than about trade-offs among hardware, software, and the kind of work you expect to do. All three camps have real strengths. macOS offers a polished, low-friction experience on Apple Silicon, with impressive power efficiency and strong support for local inference and lightweight fine-tuning. Windows is the most flexible consumer platform for pairing modern NVIDIA GPUs with mainstream desktop workflows, and WSL2 has narrowed the gap with Linux considerably. Linux remains the closest match to the software environment used in professional AI infrastructure, with the broadest native support for CUDA, containers, automation, and server-style workflows; BSD, while more niche, can be attractive for users who prioritize storage integrity and system control.
+For a home AI research lab, the operating-system question is less about which platform is “best” in the abstract and more about which one best fits the workloads, hardware, and maintenance appetite you actually have. macOS, Windows, and Linux/BSD all offer credible paths into local LLM inference, fine-tuning, and image generation, but they optimize for different priorities. Apple Silicon Macs emphasize integrated memory, efficiency, and ease of use. Windows emphasizes broad hardware support and NVIDIA compatibility with a familiar desktop environment. Linux emphasizes direct control, reproducibility, and server-grade workflows. A strong home lab should therefore be built around the OS that matches the intended balance of local experimentation, daily usability, and long-term maintainability.
 
-On cost and hardware, the divide is clear. Windows and Linux generally win on price-performance if your goal is maximum GPU throughput, because both let you build or upgrade commodity x86 systems around NVIDIA RTX cards, still the center of gravity for home AI training and image-generation workloads. They also support a wider range of motherboards, storage, networking gear, and multi-GPU configurations. macOS, by contrast, is less modular and often more expensive upfront, but Apple Silicon machines deliver something unusual: quiet, compact systems with capable integrated acceleration and unified memory that can be very effective for local inference, quantized models, and practical experimentation without the heat, noise, and power draw of a discrete-GPU tower. For buyers who value efficiency and simplicity over upgradeability, that premium can be justified.
+macOS is especially compelling when the goal is a compact, low-noise, local-first lab rather than a maximum-throughput training server. High-memory Apple Silicon machines can run quantized open-weight models, embedding pipelines, RAG systems, and image-generation workflows with a level of convenience that is hard to match on a separate GPU workstation. Tools such as MLX, MLX-LM, llama.cpp, Ollama, LM Studio, PyTorch MPS, and Hugging Face’s local inference stack have made Apple Silicon far more capable for practical AI experimentation than earlier generations of Macs. The platform’s strengths are its unified memory architecture, Unix-based developer environment, strong power efficiency, and the ability to keep a powerful local server in a small space without the noise and heat of a traditional GPU rig. Its limitations are equally clear: it does not run NVIDIA CUDA, it is less flexible for large-scale training workloads, and the cost of high-memory configurations can be substantial. macOS is therefore best suited to solo researchers and small teams whose primary needs are local inference, prototyping, evaluation, embeddings, and efficient fine-tuning rather than large multi-GPU training.
 
-Software ecosystem and GPU support are where the distinctions matter most. Linux is still the native habitat of modern ML tooling: CUDA stacks, PyTorch, JAX, DeepSpeed, vLLM, containerized workflows, and many research repos tend to work there first. It is also the best path for AMD ROCm users. Windows is close behind for NVIDIA-centric labs, with broad support for PyTorch, TensorFlow, ONNX Runtime, Stable Diffusion toolchains, and local-LLM front ends, plus the practical advantage of running desktop applications and Linux tooling side by side through WSL2. macOS has improved substantially, especially for inference and smaller-scale development via Metal, MLX, Core ML, llama.cpp, and Apple-optimized PyTorch paths, but it remains less universal for cutting-edge training stacks and does not offer the same straightforward path to top-end discrete GPU performance.
+Windows offers the broadest practical hardware foundation for many home labs, particularly when NVIDIA GPUs are involved. Its advantage is not merely that it supports CUDA natively, but that it pairs that support with a mature consumer ecosystem and WSL2, which gives access to a near-native Linux environment for tools, containers, and workflows that expect a Linux userspace. That combination allows a home researcher to use Visual Studio Code, Docker Desktop, PyTorch, Hugging Face, TensorBoard, Ollama, llama.cpp, and ComfyUI-style image-generation pipelines while retaining a familiar desktop operating system. Windows also supports a wider range of consumer and workstation GPUs than macOS, and with DirectML, ONNX Runtime, and OpenVINO it can accommodate AMD and Intel acceleration when needed. Its trade-offs are that driver and hardware fragmentation can create more debugging complexity, and WSL2, while excellent, is still an abstraction layer that occasionally complicates containerized or GPU-dependent workflows. Windows is therefore a strong choice for users who want the greatest hardware flexibility, especially when building a high-VRAM local lab around NVIDIA GPUs while still having access to Linux-based tooling.
 
-Ease of use depends on what kind of friction you are trying to avoid. macOS is arguably the easiest platform to live with day to day: strong Unix underpinnings, consistent hardware support, and minimal driver drama make it appealing for researchers who want to spend more time experimenting than debugging. Windows is often the easiest place to start for users already comfortable with consumer PC hardware, especially if they want one machine for AI, productivity, and general use; its broad driver support and huge volume of community tutorials are practical advantages. Linux has the steepest learning curve for some users, but it rewards that investment with superior reproducibility, remote-management habits, and alignment with cloud and lab infrastructure. BSD is best understood as a specialist option rather than a mainstream recommendation for AI compute itself.
+Linux and BSD are the most natural foundations for a serious, reproducible home research environment. They offer direct control over drivers, kernel settings, container runtimes, and ML frameworks, which is valuable when running multiple workloads such as LLM inference, fine-tuning, image generation, and long-running services on the same machine. Ubuntu, Debian, and Fedora provide mature paths for CUDA, PyTorch, Docker, Podman, vLLM, llama.cpp, Stable Diffusion, and ComfyUI, while FreeBSD can add meaningful value for data integrity, snapshots, and isolated workloads. The main drawback is that Linux generally demands more setup, maintenance, and troubleshooting than macOS or Windows. Driver issues, kernel updates, and container configuration are more visible, and the experience is less turnkey for users who prefer a consumer desktop. For that reason, Linux is best suited to researchers who value control, reproducibility, and a server-like environment over maximum convenience.
 
-The best choice, then, depends on your scenario. If your lab is centered on local inference, scripting, evaluation, and moderate fine-tuning in a quiet, power-efficient machine, macOS is an excellent fit. If you want the strongest all-around home setup for NVIDIA GPUs, image generation, and mixed desktop/Linux workflows, Windows is highly compelling. If you are building a serious research environment that mirrors production or cloud infrastructure, expect to use containers heavily, or want maximum compatibility with the latest open-source training stacks, Linux is the strongest foundation.
-
-My recommendation is nuanced but clear: for most serious home AI labs, Linux is the best long-term platform, with Ubuntu, Debian, or Fedora the safest bets. Windows is the best choice for users who want top consumer GPU performance with less lifestyle disruption, especially on a single versatile workstation. macOS is the best choice for researchers who prioritize stability, efficiency, and a tightly integrated system over absolute training performance. In other words, choose Linux for infrastructure fidelity, Windows for GPU-driven versatility, and macOS for elegant, low-maintenance local experimentation.
+The clearest recommendation is to choose the operating system that matches the primary use case of the lab. If the priority is a quiet, efficient, low-maintenance environment for local inference, embeddings, RAG, and modest fine-tuning, macOS on Apple Silicon is an excellent choice. If the priority is maximum GPU flexibility, especially with NVIDIA hardware, and the user wants a familiar desktop with access to both native Windows tools and Linux-based workflows, Windows with WSL2 is likely the most practical all-round option. If the lab will run multiple long-lived services, containerized experiments, and demanding local workloads, Linux is the strongest foundation, with FreeBSD a valuable companion for storage isolation and data protection. In practice, the best home AI lab is not the one built on the most ideological platform, but the one whose operating system best aligns with the hardware, workflow, and maintenance model the researcher can sustain over time.