robot_lab 0.2.1 → 0.2.7

data/docs/examples/multi-robot-network.md

@@ -6,11 +6,22 @@ Customer service system with intelligent routing using SimpleFlow pipelines.
 
 This example demonstrates a multi-robot network where a classifier routes customer inquiries to specialized support robots using SimpleFlow's optional task activation.
 
+The runnable version is
+[`examples/03_network.rb`](https://github.com/MadBomber/robot_lab/blob/main/examples/03_network.rb);
+the snippets here expand it with a fourth specialist and per-task configuration.
+
+> [!IMPORTANT]
+> Two names are in play and they are easy to confuse.
+> `result.activate(:x)` takes a **task** name (the first argument to `task`), while
+> `result.with_context(@name.to_sym, ...)` keys the context by the **robot's** name.
+> Activating a task name that was never declared **raises `ArgumentError` and aborts
+> the run** — it is not a silent no-op. Give each robot the same name as its task and
+> both problems disappear.
+
 ## Complete Example
 
 ```ruby
 #!/usr/bin/env ruby
-# examples/customer_service.rb
 
 require "bundler/setup"
 require "robot_lab"
@@ -185,17 +196,26 @@ class ClassifierRobot < RobotLab::Robot
       .with_context(@name.to_sym, robot_result)
       .continue(robot_result)
 
-    # 5. Activate the appropriate optional task based on output
+    # 5. Activate the appropriate optional task based on output.
+    #    These symbols MUST match the task names declared in create_network.
     category = robot_result.last_text_content.to_s.strip.downcase
     case category
-    when /billing/ then new_result.activate(:billing)
-    when /technical/ then new_result.activate(:technical)
-    else new_result.activate(:general)
+    when /billing/ then new_result.activate(:billing_agent)
+    when /technical/ then new_result.activate(:tech_agent)
+    else new_result.activate(:general_agent)
     end
   end
 end
 ```
 
+> [!WARNING]
+> `activate` validates its argument and **raises**. Activating `:billing` when the
+> network declared `task :billing_agent, ...` aborts the run with
+> `ArgumentError: Step :classifier attempted to activate unknown step :billing`.
+> Activating a task that was *not* declared `depends_on: :optional` raises too:
+> `ArgumentError: Step :classifier attempted to activate non-optional step :billing_agent.`
+> Use `result.activated_steps` to inspect what routing actually did.
+
 !!! note "extract_run_context"
     The `extract_run_context(result)` method is a protected helper on `Robot`. It extracts `run_params` from the SimpleFlow result context, handles value propagation from previous steps, and separates robot-specific params (`mcp:`, `tools:`, `memory:`, `network_memory:`) from the message and other context.
 
@@ -245,22 +265,43 @@ end
 
 ## Per-Task Configuration
 
-Tasks can have individual context, tools, and MCP servers:
+Tasks can carry their own context, a tool allowlist, and MCP servers:
 
 ```ruby
+# Tools must already be ATTACHED to the robot...
+billing_agent = RobotLab.build(
+  name: "billing_agent",
+  system_prompt: "You handle billing.",
+  local_tools: [RefundTool, InvoiceTool, AuditTool]
+)
+
 network = RobotLab.create_network(name: "support") do
   task :classifier, classifier, depends_on: :none
   task :billing_agent, billing_agent,
        context: { department: "billing", escalation_level: 2 },
-       tools: [RefundTool, InvoiceTool],
+       tools: [RefundTool, InvoiceTool],   # ...and this SELECTS from them
        depends_on: :optional
   task :tech_agent, tech_agent,
        context: { department: "technical" },
        mcp: [filesystem_server],
+       tools: :inherit,                    # send every discovered MCP tool
        depends_on: :optional
 end
 ```
 
+> [!WARNING]
+> Per-task `tools:` is an **allowlist over tools the robot already has** — it never
+> attaches anything. Give a task `tools: [RefundTool]` for a robot whose
+> `local_tools` are empty and it sends zero tools.
+>
+> Matching is by string comparison against each attached tool's `name`, so the two
+> sides must agree. `local_tools: [RefundTool]` (the class) matches
+> `tools: [RefundTool]`, but `local_tools: [RefundTool.new]` (an instance, whose
+> name is `"refund"`) does not — use `tools: %w[refund]` there.
+>
+> Omitting `tools:` from a task means `:none`: the robot sends no tools at all.
+> Use `tools: :inherit` for "send everything attached".
+
 The `Task` wrapper deep-merges per-task context with the network's run params before delegating to the robot's `call` method.
 
 ## Pipeline Pattern
@@ -298,13 +339,19 @@ puts result.value.last_text_content
 Fan-out / fan-in pattern where multiple robots analyze in parallel and a synthesizer merges results:
 
 ```ruby
+# Robot names deliberately match their task names -- result.context is keyed
+# by the ROBOT's name, so mismatched names produce nil lookups below.
+sentiment = RobotLab.build(name: "sentiment", system_prompt: "Score sentiment.")
+entities  = RobotLab.build(name: "entities",  system_prompt: "Extract entities.")
+keywords  = RobotLab.build(name: "keywords",  system_prompt: "Extract keywords.")
+
 network = RobotLab.create_network(name: "multi_analysis") do
   task :prepare, preparer, depends_on: :none
 
   # These run in parallel (all depend on :prepare)
-  task :sentiment, sentiment_analyzer, depends_on: [:prepare]
-  task :entities, entity_extractor, depends_on: [:prepare]
-  task :keywords, keyword_extractor, depends_on: [:prepare]
+  task :sentiment, sentiment, depends_on: [:prepare]
+  task :entities, entities, depends_on: [:prepare]
+  task :keywords, keywords, depends_on: [:prepare]
 
   # Waits for all three to complete
   task :summarize, summarizer, depends_on: [:sentiment, :entities, :keywords]
@@ -312,13 +359,19 @@ end
 
 result = network.run(message: "Analyze this text")
 
-# Access parallel results from context
+# Access parallel results from context (keyed by robot name)
 puts "Sentiment: #{result.context[:sentiment].last_text_content}"
 puts "Entities: #{result.context[:entities].last_text_content}"
 puts "Keywords: #{result.context[:keywords].last_text_content}"
 puts "Summary: #{result.value.last_text_content}"
 ```
 
+> [!WARNING]
+> `result.context` is keyed by `@name` of the robot that wrote it, not by the task
+> name. Had these robots kept names like `sentiment_analyzer`, the lookups above
+> would return `nil` even though every task ran. Keep robot name and task name
+> identical.
+
 ## Shared Memory in Networks
 
 Networks provide a shared `Memory` instance that all robots can read and write. This is especially useful for parallel robots that need to coordinate:
@@ -374,30 +427,47 @@ network = RobotLab.create_network(name: "validated_pipeline") do
 end
 
 result = network.run(message: "Process this")
-if result.halted?
-  puts "Validation failed: #{result.value.last_text_content}"
-else
+if result.continue?
   puts "Processing complete: #{result.value.last_text_content}"
+else
+  puts "Validation failed: #{result.value.last_text_content}"
 end
 ```
 
+> [!WARNING]
+> `SimpleFlow::Result` has **no** `halted?` or `continued?` predicate — calling
+> either raises `NoMethodError`. The predicate is `continue?`, which returns
+> `false` after `halt`. The full public API is exactly `activate`,
+> `activated_steps`, `context`, `continue`, `continue?`, `errors`, `halt`, `value`,
+> `with_context`, and `with_error`. `with_value` is **private** — calling it raises
+> `NoMethodError`; use `continue(value)` or `halt(value)` to set the value.
+
 ## Running
 
 ```bash
 export ANTHROPIC_API_KEY="your-key"
-ruby examples/customer_service.rb
+
+# Classifier + three specialists with optional-task routing
+ruby examples/03_network.rb
+
+# Shared reactive memory across concurrent robots
+ruby examples/07_network_memory.rb
+
+# Network visualization and introspection (no LLM calls)
+ruby examples/11_network_introspection.rb
 ```
 
 ## Key Concepts
 
-1. **SimpleFlow Pipeline**: DAG-based execution with dependency management via `depends_on:`
+1. **SimpleFlow Pipeline**: DAG-based execution with dependency management via `depends_on:`. The DSL method is `task` — there is no `step`, no `router:` kwarg, and no `Router` class
 2. **Optional Tasks**: Use `depends_on: :optional` for tasks activated dynamically by classifiers
-3. **Robot#call Override**: Custom routing logic in classifier robots that override the `call` method
+3. **Robot#call Override**: Routing is written in Ruby — subclass `Robot`, override `call`, and call `result.activate(:task_name)`
 4. **extract_run_context**: Helper method to extract message and params from `SimpleFlow::Result`
-5. **Context Flow**: Data passed through `result.context` and accessed by downstream robots
-6. **Parallel Execution**: Tasks with the same dependencies run concurrently
-7. **Shared Memory**: Network memory (`network_memory:`) enables inter-robot communication
-8. **Per-Task Configuration**: Each task can have its own context, tools, and MCP servers via `Task`
+5. **Context Flow**: `result.context` is keyed by the **robot's** name (`with_context(@name.to_sym, ...)`), while `activate` takes a **task** name — keep the two identical
+6. **Result predicates**: `continue?` (not `halted?`), plus `activated_steps` to see what routing actually did
+7. **Parallel Execution**: Tasks with the same dependencies run concurrently; cap in-flight LLM calls with `RunConfig.new(max_concurrent_robots: N)`
+8. **Shared Memory**: Network memory (`network_memory:`) enables inter-robot communication
+9. **Per-Task Configuration**: Each task can carry its own context, MCP servers, and a `tools:` allowlist over the robot's already-attached tools
 
 ## See Also
 

data/docs/examples/tool-usage.md

@@ -6,13 +6,36 @@ Robots with external capabilities through tools.
 
 This example demonstrates how to give robots access to external systems through tools. Tools are defined as `RubyLLM::Tool` subclasses or `RobotLab::Tool` instances and passed to robots via the `local_tools:` parameter.
 
+> [!WARNING]
+> **Attaching a tool is not the same as sending it.** `Robot#run` defaults to
+> `tools: :none`, so a plain `robot.run("...")` sends the LLM zero tools even when
+> `local_tools:` were supplied at build time. Pass `tools: :inherit` on every call
+> that should be able to use them:
+>
+> ```ruby
+> robot.run("What is 15 * 7?", tools: :inherit)
+> ```
+>
+> For a **standalone** robot, do not pass `tools: :inherit` in the constructor:
+> at build time it resolves against the parent level (`:none`) and yields an
+> allowlist matching nothing, suppressing the tools even when the run asks for
+> them. Leave `tools:` unset there.
+>
+> Inside a **network**, the opposite holds — build-time `tools: :inherit` is how a
+> robot opts into the network `config:`'s allowlist. See
+> [Creating Networks](../guides/creating-networks.md).
+>
+> An explicit array (`tools: [Calculator]`) is an allowlist, not a local-vs-MCP
+> switch, and its entries must match how each tool was attached — this page
+> attaches classes, so use class names.
+
 ## RubyLLM::Tool Subclass Pattern
 
 The primary way to define tools is by subclassing `RubyLLM::Tool`:
 
 ```ruby
 #!/usr/bin/env ruby
-# examples/tool_usage.rb
+# Tool definitions mirror examples/02_tools.rb
 
 require "bundler/setup"
 require "robot_lab"
@@ -79,21 +102,26 @@ robot = RobotLab.build(
   model: "claude-sonnet-4"
 )
 
-# Run the robot
-result = robot.run("What is 15 multiplied by 7? Also, give me a career fortune.")
+# Run the robot -- tools: :inherit is what actually sends Calculator and
+# FortuneCookie to the LLM
+result = robot.run(
+  "What is 15 multiplied by 7? Also, give me a career fortune.",
+  tools: :inherit
+)
 
 # Display results
 puts "Response: #{result.last_text_content}"
 
-if result.tool_calls.any?
-  puts "\nTool calls made:"
-  result.tool_calls.each do |tc|
-    tool_info = tc.respond_to?(:tool) ? tc.tool : tc
-    puts "  #{tool_info[:name] || tool_info}"
-  end
-end
+# Confirm which tools were sent for this turn
+puts "Tools sent: #{robot.chat.tools.keys.join(', ')}"
 ```
 
+> [!NOTE]
+> `result.tool_calls` is effectively always empty. It reads the *final* assistant
+> message, and by the time ruby_llm's tool loop has finished that message contains
+> only text. To observe tool activity, use the `on_tool_call:` callback (below) or
+> the `:tool_call` hooks.
+
 ## RobotLab::Tool.create Pattern
 
 For simpler tools that do not need their own class, use `RobotLab::Tool.create`:
@@ -127,15 +155,22 @@ robot = RobotLab.build(
   model: "claude-sonnet-4"
 )
 
-result = robot.run("What time is it and what's the weather in New York?")
+result = robot.run("What time is it and what's the weather in New York?", tools: :inherit)
 puts result.last_text_content
 ```
 
+The block receives a single hash of symbol-keyed arguments.
+
+> [!NOTE]
+> `RobotLab::Tool.create(parameters:)` accepts a JSON-Schema-shaped hash, but only
+> `type` and `description` are read off each property, plus the top-level `required`
+> list. Anything else (`enum`, `default`, nested `items`) is ignored — ruby_llm's
+> `param` DSL supports only `type:`, `desc:`/`description:`, and `required:`.
+
 ## Weather API Integration
 
 ```ruby
 #!/usr/bin/env ruby
-# examples/weather_assistant.rb
 
 require "bundler/setup"
 require "robot_lab"
@@ -227,7 +262,7 @@ loop do
   break if input.nil? || input.downcase == "quit"
   next if input.empty?
 
-  result = weather_bot.run(input)
+  result = weather_bot.run(input, tools: :inherit)
   puts "\nAssistant: #{result.last_text_content}"
 end
 
@@ -237,8 +272,6 @@ puts "\nGoodbye!"
 ## Database Integration
 
 ```ruby
-# examples/order_assistant.rb
-
 require "robot_lab"
 
 # Mock database
@@ -297,7 +330,7 @@ order_bot = RobotLab.build(
 )
 
 # Run with a question
-result = order_bot.run("What's the status of order ORD001?")
+result = order_bot.run("What's the status of order ORD001?", tools: :inherit)
 puts result.last_text_content
 ```
 
@@ -314,27 +347,41 @@ robot = RobotLab.build(
   on_tool_call: ->(tool_call) {
     puts "[Tool Call] #{tool_call.name}: #{tool_call.arguments}"
   },
-  on_tool_result: ->(tool_call, result) {
-    puts "[Tool Result] #{tool_call.name}: #{result}"
+  # NOTE: one argument -- the result. There is no tool_call parameter here.
+  on_tool_result: ->(result) {
+    puts "[Tool Result] #{result}"
   }
 )
 
-result = robot.run("What is 42 * 17?")
+result = robot.run("What is 42 * 17?", tools: :inherit)
 ```
 
+> [!WARNING]
+> `on_tool_result` receives **exactly one** argument, the tool's return value.
+> Writing `->(tool_call, result)` raises
+> `ArgumentError: wrong number of arguments (given 1, expected 2)` the first time a
+> tool runs.
+>
+> Both callbacks map onto ruby_llm's legacy hooks and are deprecated as of
+> ruby_llm 1.16 — wiring either one emits
+> ``` `on_tool_call` is deprecated and will be removed in RubyLLM 2.0. Use `before_tool_call` instead. ```
+> The additive replacements are `before_message`, `after_message`,
+> `before_tool_call`, and `after_tool_result`. RobotLab's own
+> [Hook system](../guides/hooks.md) is the supported way to observe tool activity.
+
 ## Running
 
 ```bash
 export ANTHROPIC_API_KEY="your-key"
 
-# Tool usage example
-ruby examples/tool_usage.rb
+# Tool definitions and a robot that uses them
+ruby examples/02_tools.rb
 
-# Weather assistant
-ruby examples/weather_assistant.rb
+# Tool loop circuit breaker (max_tool_rounds)
+ruby examples/20_circuit_breaker.rb
 
-# Order lookup
-ruby examples/order_assistant.rb
+# Ractor-safe CPU tools (no LLM calls)
+ruby examples/29_ractor_tools.rb
 ```
 
 ## Interactive User Input
@@ -348,17 +395,30 @@ robot = RobotLab.build(
   name: "interviewer",
   system_prompt: <<~PROMPT,
     You are a project setup assistant. Interview the user to understand their
-    needs, then summarize the project plan. Use the ask_user tool to gather
-    information one question at a time.
+    needs, then summarize the project plan. Use the robot_lab--ask_user tool to
+    gather information one question at a time.
   PROMPT
-  local_tools: [RobotLab::AskUser],
   model: "claude-sonnet-4"
 )
 
-result = robot.run("Help me plan a new web application")
+# Attach an INSTANCE bound to the robot so the tool uses robot.input/robot.output
+robot.local_tools << RobotLab::AskUser.new(robot: robot)
+
+result = robot.run("Help me plan a new web application", tools: :inherit)
 puts "\nProject Plan:\n#{result.last_text_content}"
 ```
 
+> [!WARNING]
+> Pass an **instance**, not the class. `RobotLab::Tool` derives its LLM-visible
+> name from the full class name, so `RobotLab::AskUser` is presented to the model
+> as **`robot_lab--ask_user`**, not `ask_user` — name it that way in your system
+> prompt.
+>
+> An instance created without `robot:` has `tool.robot == nil`, so it ignores
+> `robot.input` / `robot.output`, falls back to `$stdin` / `$stdout`, and labels
+> every prompt `[Robot]` instead of the robot's name. Always use
+> `RobotLab::AskUser.new(robot: robot)`.
+
 The robot will ask questions interactively:
 
 ```
@@ -375,24 +435,31 @@ The robot will ask questions interactively:
 > Customer support portal
 ```
 
-For testing, inject `StringIO` objects:
+For testing, inject `StringIO` objects on the robot *before* building the tool
+instance (the tool reads them through its `robot` reference at call time):
 
 ```ruby
 robot.input  = StringIO.new("Ruby\nyes\nCustomer portal\n")
 robot.output = StringIO.new
 ```
 
+`RobotLab::AskUser` can also be driven directly, outside an LLM turn — see
+[`examples/06_prompt_templates.rb`](https://github.com/MadBomber/robot_lab/blob/main/examples/06_prompt_templates.rb),
+which calls `RobotLab::AskUser.new.call("question" => ..., "default" => ...)` to
+collect a value before any robot is built.
+
 ## Key Concepts
 
 1. **RubyLLM::Tool subclass**: Define a class with `description`, `param`, and `execute` method
-2. **RobotLab::Tool subclass**: Same DSL plus `robot` accessor for robot-aware tools
+2. **RobotLab::Tool subclass**: Same DSL plus a `robot` accessor for robot-aware tools
 3. **RobotLab::Tool.create**: Use `RobotLab::Tool.create(name:, description:, &block)` for dynamic tools
-4. **Built-in tools**: `RobotLab::AskUser` for interactive terminal input
-5. **local_tools**: Pass tool classes/instances via `local_tools:` parameter to `RobotLab.build` or `Robot.new`
-6. **Frontmatter tools**: Declare tool class names in template YAML front matter (`tools: [Calculator]`) for self-contained templates
-7. **Error Handling**: Return error hashes (e.g., `{ error: "message" }`) for graceful failures
-8. **Callbacks**: Use `on_tool_call:` and `on_tool_result:` for monitoring
-9. **Result Access**: Check `result.tool_calls` for tool call history, `result.last_text_content` for the final response
+4. **Built-in tools**: `RobotLab::AskUser` (LLM-visible name `robot_lab--ask_user`) for interactive terminal input
+5. **local_tools**: Pass tool classes/instances via `local_tools:` to `RobotLab.build` or `Robot.new` — this *attaches* them
+6. **tools: :inherit**: Required on `run` to actually *send* the attached tools; the default is `tools: :none`
+7. **Frontmatter tools**: Declare tool class names in template YAML front matter (`tools: [Calculator]`); they populate `local_tools`, and still need `tools: :inherit` at run time. Constructor `local_tools:` overrides the front-matter list
+8. **Error Handling**: Raised exceptions are caught and returned to the LLM as text (`"Error (tool_name): message"`); a `RobotLab::ToolError` with `retryable: true` appends `" (retryable)"`. Set `self.raise_on_error = true` on a class to opt out — note this is per-class and is *not* inherited by subclasses
+9. **Tool cap**: At most `DEFAULT_MAX_TOOLS` (128) tools are sent. Setting `max_tools` to nil, 0, or a negative number falls back to 128 — the cap cannot be disabled
+10. **Result Access**: Use `result.last_text_content` (alias `result.reply`) for the final response. `result.tool_calls` is effectively always empty — observe tool activity with `on_tool_call:` or the Hook system instead
 
 ## See Also