robot_lab 0.0.1 → 0.0.4

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

@@ -4,7 +4,7 @@ Customer service system with intelligent routing using SimpleFlow pipelines.
 
 ## Overview
 
-This example demonstrates a multi-robot network where a classifier routes customer inquiries to specialized support robots using optional task activation.
+This example demonstrates a multi-robot network where a classifier routes customer inquiries to specialized support robots using SimpleFlow's optional task activation.
 
 ## Complete Example
 
@@ -15,14 +15,12 @@ This example demonstrates a multi-robot network where a classifier routes custom
 require "bundler/setup"
 require "robot_lab"
 
-RobotLab.configure do |config|
-  config.default_model = "claude-sonnet-4"
-end
-
 # Custom classifier that routes to specialists
 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)
@@ -44,7 +42,7 @@ end
 classifier = ClassifierRobot.new(
   name: "classifier",
   description: "Classifies customer inquiries",
-  system_prompt: <<~PROMPT
+  system_prompt: <<~PROMPT,
     You are a customer inquiry classifier. Analyze the customer's message
     and respond with exactly ONE of these categories:
 
@@ -55,13 +53,14 @@ classifier = ClassifierRobot.new(
 
     Respond with ONLY the category name, nothing else.
   PROMPT
+  model: "claude-sonnet-4"
 )
 
 # Billing specialist
 billing_agent = RobotLab.build(
   name: "billing_agent",
   description: "Handles billing inquiries",
-  system_prompt: <<~PROMPT
+  system_prompt: <<~PROMPT,
     You are a billing support specialist. You help customers with:
     - Payment issues and refunds
     - Invoice questions
@@ -70,13 +69,14 @@ billing_agent = RobotLab.build(
 
     Be helpful, empathetic, and provide clear next steps.
   PROMPT
+  model: "claude-sonnet-4"
 )
 
 # Technical support
 tech_agent = RobotLab.build(
   name: "tech_agent",
   description: "Handles technical issues",
-  system_prompt: <<~PROMPT
+  system_prompt: <<~PROMPT,
     You are a technical support specialist. You help customers with:
     - Bug reports and troubleshooting
     - Feature explanations
@@ -85,13 +85,14 @@ tech_agent = RobotLab.build(
 
     Ask clarifying questions when needed. Provide step-by-step solutions.
   PROMPT
+  model: "claude-sonnet-4"
 )
 
 # Account specialist
 account_agent = RobotLab.build(
   name: "account_agent",
   description: "Handles account issues",
-  system_prompt: <<~PROMPT
+  system_prompt: <<~PROMPT,
     You are an account support specialist. You help customers with:
     - Login and authentication issues
     - Profile and settings changes
@@ -100,13 +101,14 @@ account_agent = RobotLab.build(
 
     Prioritize security while being helpful.
   PROMPT
+  model: "claude-sonnet-4"
 )
 
 # General support
 general_agent = RobotLab.build(
   name: "general_agent",
   description: "Handles general inquiries",
-  system_prompt: <<~PROMPT
+  system_prompt: <<~PROMPT,
     You are a general support agent. You help customers with:
     - Product information
     - General questions
@@ -115,6 +117,7 @@ general_agent = RobotLab.build(
 
     Be friendly and informative.
   PROMPT
+  model: "claude-sonnet-4"
 )
 
 # Create the network with optional task routing
@@ -161,16 +164,53 @@ test_inquiries.each do |inquiry|
 end
 ```
 
-## With Context Passing
+## ClassifierRobot Pattern
+
+The key to conditional routing is overriding the `call` method. The base `Robot#call` extracts the message from the `SimpleFlow::Result` and calls `run`. A classifier overrides this to inspect the output and activate the appropriate optional task:
 
 ```ruby
-# Enhanced version with additional context
+class ClassifierRobot < RobotLab::Robot
+  def call(result)
+    # 1. Extract run context from the SimpleFlow result
+    context = extract_run_context(result)
+
+    # 2. Pull out the message (it's a key in the context hash)
+    message = context.delete(:message)
+
+    # 3. Run the robot to get a classification
+    robot_result = run(message, **context)
+
+    # 4. Store our result and continue the pipeline
+    new_result = result
+      .with_context(@name.to_sym, robot_result)
+      .continue(robot_result)
+
+    # 5. Activate the appropriate optional task based on output
+    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)
+    end
+  end
+end
+```
+
+!!! 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.
 
+## With Context Passing
+
+Enhanced version where the classifier passes additional context to specialists:
+
+```ruby
 class ContextAwareClassifier < 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)
 
-    # Store classification in context for specialist
+    # Store classification and original message in context for specialist
     new_result = result
       .with_context(@name.to_sym, robot_result)
       .with_context(:classification, robot_result.last_text_content.strip)
@@ -193,11 +233,10 @@ class BillingAgent < RobotLab::Robot
     classification = result.context[:classification]
     original_message = result.context[:original_message]
 
-    robot_result = run(
-      **extract_run_context(result),
-      classification: classification,
-      customer_message: original_message
-    )
+    context = extract_run_context(result)
+    message = context.delete(:message)
+
+    robot_result = run(message, **context)
 
     result.with_context(@name.to_sym, robot_result).continue(robot_result)
   end
@@ -206,8 +245,9 @@ end
 
 ## Per-Task Configuration
 
+Tasks can have individual context, tools, and MCP servers:
+
 ```ruby
-# Tasks with individual context and tools
 network = RobotLab.create_network(name: "support") do
   task :classifier, classifier, depends_on: :none
   task :billing_agent, billing_agent,
@@ -216,15 +256,33 @@ network = RobotLab.create_network(name: "support") do
        depends_on: :optional
   task :tech_agent, tech_agent,
        context: { department: "technical" },
-       mcp: [FilesystemServer],
+       mcp: [filesystem_server],
        depends_on: :optional
 end
 ```
 
+The `Task` wrapper deep-merges per-task context with the network's run params before delegating to the robot's `call` method.
+
 ## Pipeline Pattern
 
+Sequential processing pipeline where each robot depends on the previous:
+
 ```ruby
-# Sequential processing pipeline
+extractor = RobotLab.build(
+  name: "extractor",
+  system_prompt: "Extract key information from documents."
+)
+
+analyzer = RobotLab.build(
+  name: "analyzer",
+  system_prompt: "Analyze extracted data and provide insights."
+)
+
+formatter = RobotLab.build(
+  name: "formatter",
+  system_prompt: "Format analysis results into a clear report."
+)
+
 network = RobotLab.create_network(name: "document_processor") do
   task :extract, extractor, depends_on: :none
   task :analyze, analyzer, depends_on: [:extract]
@@ -237,35 +295,69 @@ puts result.value.last_text_content
 
 ## Parallel Analysis Pattern
 
+Fan-out / fan-in pattern where multiple robots analyze in parallel and a synthesizer merges results:
+
 ```ruby
-# Fan-out / fan-in pattern
-network = RobotLab.create_network(name: "multi_analysis", concurrency: :threads) do
+network = RobotLab.create_network(name: "multi_analysis") do
   task :prepare, preparer, depends_on: :none
 
-  # These run in parallel
+  # 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]
 
-  # Waits for all three
+  # Waits for all three to complete
   task :summarize, summarizer, depends_on: [:sentiment, :entities, :keywords]
 end
 
 result = network.run(message: "Analyze this text")
 
-# Access parallel results
+# Access parallel results from context
 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}"
 ```
 
+## 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:
+
+```ruby
+class AnalysisRobot < RobotLab::Robot
+  def initialize(memory_key:, **opts)
+    super(**opts)
+    @memory_key = memory_key
+  end
+
+  def call(result)
+    context = extract_run_context(result)
+    network_memory = context.delete(:network_memory)
+    message = context.delete(:message)
+
+    robot_result = run(message, network_memory: network_memory, **context)
+
+    # Write parsed results to shared memory
+    if network_memory
+      network_memory.current_writer = @name
+      network_memory.set(@memory_key, robot_result.last_text_content)
+    end
+
+    result.with_context(@name.to_sym, robot_result).continue(robot_result)
+  end
+end
+```
+
 ## Conditional Halting
 
+Use `result.halt` to stop the pipeline early:
+
 ```ruby
 class ValidatorRobot < 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)
 
     if robot_result.last_text_content.include?("INVALID")
       # Halt the pipeline early
@@ -298,12 +390,14 @@ ruby examples/customer_service.rb
 
 ## Key Concepts
 
-1. **SimpleFlow Pipeline**: DAG-based execution with dependency management
-2. **Optional Tasks**: Activated dynamically based on classification
-3. **Robot#call**: Custom routing logic in classifier robots
-4. **Context Flow**: Data passed through `result.context`
-5. **Parallel Execution**: Tasks with same dependencies run concurrently
-6. **Per-Task Configuration**: Each task can have its own context, tools, and MCP servers
+1. **SimpleFlow Pipeline**: DAG-based execution with dependency management via `depends_on:`
+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
+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`
 
 ## See Also