robot_lab 0.0.1 → 0.0.4

data/docs/index.md

@@ -11,7 +11,7 @@
 </td>
 <td width="50%" valign="top">
 RobotLab is a Ruby gem that enables you to build sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks.<br><br>
-Each robot has its own system prompt, tools, and capabilities. Robots can be orchestrated through networks with customizable routing logic, share information through a hierarchical memory system, and connect to external tools via the Model Context Protocol (MCP).
+Each robot is backed by a persistent LLM chat, configured with keyword arguments, and run with a simple positional message. Robots can be orchestrated through networks with task-based pipelines, share information through a reactive memory system, and connect to external tools via the Model Context Protocol (MCP).
 </td>
 </tr>
 </table>
@@ -24,7 +24,7 @@ Each robot has its own system prompt, tools, and capabilities. Robots can be orc
 
     ---
 
-    Build applications with multiple specialized AI agents, each with unique capabilities and personalities.
+    Build applications with multiple specialized AI agents, each inheriting from `RubyLLM::Agent` with persistent chat and memory.
 
     [:octicons-arrow-right-24: Learn more](architecture/core-concepts.md)
 
@@ -32,7 +32,7 @@ Each robot has its own system prompt, tools, and capabilities. Robots can be orc
 
     ---
 
-    Connect robots in networks with flexible routing to handle complex, multi-step workflows.
+    Connect robots in task-based pipelines using SimpleFlow with sequential, parallel, and conditional execution.
 
     [:octicons-arrow-right-24: Creating Networks](guides/creating-networks.md)
 
@@ -40,7 +40,7 @@ Each robot has its own system prompt, tools, and capabilities. Robots can be orc
 
     ---
 
-    Give robots custom tools to interact with external systems, databases, and APIs.
+    Give robots tools via `RubyLLM::Tool` subclasses or `RobotLab::Tool.new` with block handlers.
 
     [:octicons-arrow-right-24: Using Tools](guides/using-tools.md)
 
@@ -52,11 +52,19 @@ Each robot has its own system prompt, tools, and capabilities. Robots can be orc
 
     [:octicons-arrow-right-24: MCP Guide](guides/mcp-integration.md)
 
--   :material-memory:{ .lg .middle } **Shared Memory**
+-   :material-message-arrow-right-outline:{ .lg .middle } **Message Bus**
 
     ---
 
-    Robots can share information through a hierarchical memory system with namespaced scopes.
+    Enable bidirectional, cyclic communication between robots via TypedBus for negotiation loops and convergence patterns.
+
+    [:octicons-arrow-right-24: Message Bus](architecture/core-concepts.md#message-bus)
+
+-   :material-memory:{ .lg .middle } **Reactive Memory**
+
+    ---
+
+    Robots share data through a reactive key-value memory system with subscriptions, blocking reads, and optional Redis backend.
 
     [:octicons-arrow-right-24: Memory System](guides/memory.md)
 
@@ -75,33 +83,34 @@ Each robot has its own system prompt, tools, and capabilities. Robots can be orc
 ```ruby
 require "robot_lab"
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
-  config.default_model = "claude-sonnet-4"
-end
-
-# Create a simple robot
-robot = RobotLab.build do
-  name "assistant"
-  description "A helpful AI assistant"
-  template <<~PROMPT
-    You are a helpful assistant. Answer questions clearly and concisely.
-  PROMPT
-end
-
-# Create a network with the robot
-network = RobotLab.create_network do
-  name "simple_network"
-  add_robot robot
-end
-
-# Run the network
-state = RobotLab.create_state(message: "What is the capital of France?")
-result = network.run(state: state)
-
-puts result.last_result.output.first.content
+# Configuration is automatic via environment variables, YAML files, or defaults.
+# Set API keys via env vars:
+#   ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+#
+# Or place a config file at ~/.config/robot_lab/config.yml
+# Access config values: RobotLab.config.ruby_llm.model  #=> "claude-sonnet-4"
+
+# Create a robot with keyword arguments
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are a helpful assistant. Answer questions clearly and concisely.",
+  model: "claude-sonnet-4"
+)
+
+# Run the robot with a positional string argument
+result = robot.run("What is the capital of France?")
+
+puts result.last_text_content
 # => "The capital of France is Paris."
+
+# Memory persists across runs
+robot.run("Remember that my favorite color is blue.")
+result = robot.run("What is my favorite color?")
+puts result.last_text_content
+# => "Your favorite color is blue."
+
+# Chaining configuration
+robot.with_instructions("Be extra concise.").with_temperature(0.3).run("Explain Ruby in one sentence.")
 ```
 
 ## Supported LLM Providers
@@ -110,12 +119,16 @@ RobotLab supports multiple LLM providers through the [ruby_llm](https://github.c
 
 | Provider | Models |
 |----------|--------|
-| **Anthropic** | Claude 4, Claude Sonnet, Claude Haiku |
-| **OpenAI** | GPT-4o, GPT-4, GPT-3.5 Turbo |
-| **Google** | Gemini Pro, Gemini Ultra |
-| **Azure OpenAI** | All Azure-hosted OpenAI models |
-| **Bedrock** | Claude models via AWS Bedrock |
+| **Anthropic** | Claude Opus 4, Claude Sonnet 4, Claude Haiku 3.5 |
+| **OpenAI** | GPT-4o, GPT-4, o1, o3 |
+| **Google** | Gemini 2.5 Pro, Gemini 2.5 Flash |
+| **DeepSeek** | DeepSeek V3, DeepSeek R1 |
+| **AWS Bedrock** | Claude models via AWS Bedrock |
+| **Google Vertex AI** | Gemini models via Vertex AI |
 | **Ollama** | Local models via Ollama |
+| **OpenRouter** | Multi-provider routing |
+| **Mistral** | Mistral Large, Mistral Medium |
+| **xAI** | Grok models |
 
 ## Installation
 

data/examples/01_simple_robot.rb

@@ -8,26 +8,23 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/01_simple_robot.rb
 
-require_relative "../lib/robot_lab"
+# Configure template path before loading (MywayConfig reads env vars on init)
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
-  config.template_path = File.join(__dir__, "prompts")
-end
+require_relative "../lib/robot_lab"
 
 # Create a simple robot using a template
 robot = RobotLab.build(
   name: "helper",
   template: :helper,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 puts "Running simple robot..."
 puts "-" * 40
 
-# Run the robot with a simple query
-result = robot.run(message: "What is 2 + 2? Please explain your reasoning briefly.")
+# Run the robot
+result = robot.run("What is 2 + 2? Please explain your reasoning briefly.")
 
 # Display the result
 puts "Robot: #{robot.name}"

data/examples/02_tools.rb

@@ -8,13 +8,10 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/02_tools.rb
 
-require_relative "../lib/robot_lab"
+# Configure template path before loading (MywayConfig reads env vars on init)
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
-  config.template_path = File.join(__dir__, "prompts")
-end
+require_relative "../lib/robot_lab"
 
 # Define tools using RubyLLM::Tool
 class Calculator < RubyLLM::Tool
@@ -86,15 +83,15 @@ end
 robot = RobotLab.build(
   name: "assistant",
   template: :assistant,
-  tools: [Calculator, FortuneCookie],
-  model: "claude-sonnet-4"
+  local_tools: [Calculator, FortuneCookie],
+  model: "claude-3-haiku-20240307"
 )
 
 puts "Running robot with tools..."
 puts "-" * 40
 
 # Run the robot
-result = robot.run(message: "What is 15 multiplied by 7? Also, give me a fortune about my career.")
+result = robot.run("What is 15 multiplied by 7? Also, give me a fortune about my career.")
 
 # Display results
 puts "Robot: #{robot.name}"

data/examples/03_network.rb

@@ -9,25 +9,24 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/03_network.rb
 
-require_relative "../lib/robot_lab"
+# Configure template path before loading (MywayConfig reads env vars on init)
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
-  config.template_path = File.join(__dir__, "prompts")
-end
+require_relative "../lib/robot_lab"
 
 # Classifier robot that activates the appropriate specialist
 class ClassifierRobot < RobotLab::Robot
   def call(result)
-    robot_result = run(**extract_run_context(result))
+    run_context = extract_run_context(result)
+    message = run_context.delete(:message)
+    robot_result = run(message, **run_context)
 
     new_result = result
       .with_context(@name.to_sym, robot_result)
       .continue(robot_result)
 
     # Examine LLM output and activate appropriate specialist
-    category = robot_result.last_text_content.to_s.strip.downcase
+    category = robot_result.reply.to_s.strip.downcase
 
     case category
     when /billing/
@@ -44,25 +43,25 @@ end
 classifier = ClassifierRobot.new(
   name: "classifier",
   template: :classifier,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 billing_robot = RobotLab.build(
   name: "billing",
   template: :billing,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 technical_robot = RobotLab.build(
   name: "technical",
   template: :technical,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 general_robot = RobotLab.build(
   name: "general",
   template: :general,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 # Create network with optional task routing
@@ -90,13 +89,13 @@ puts "\nConversation flow:"
 if result.context[:classifier]
   classifier_result = result.context[:classifier]
   puts "\n1. Robot: classifier"
-  puts "   Classification: #{classifier_result.last_text_content}"
+  puts "   Classification: #{classifier_result.reply}"
 end
 
 # Show specialist result (the final value)
 if result.value.is_a?(RobotLab::RobotResult)
   puts "\n2. Robot: #{result.value.robot_name}"
-  content = result.value.last_text_content
+  content = result.value.reply
   puts "   Response: #{content[0..200]}..." if content
 end
 

data/examples/04_mcp.rb

@@ -21,13 +21,10 @@
 #   - Reading file contents and repository information
 #   - Managing branches and commits
 
-require_relative "../lib/robot_lab"
+# Configure template path before loading (MywayConfig reads env vars on init)
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
-  config.template_path = File.join(__dir__, "prompts")
-end
+require_relative "../lib/robot_lab"
 
 # GitHub MCP server configuration using StdIO transport
 github_server = {
@@ -151,7 +148,7 @@ begin
     name: "github_assistant",
     template: :github_assistant,
     mcp_servers: [github_server],
-    model: "claude-sonnet-4-20250514"
+    model: "claude-3-haiku-20240307"
   )
 
   puts "Robot created: #{robot.name}"
@@ -175,7 +172,7 @@ begin
   puts "Query: 'What are the top 3 most starred Ruby web frameworks on GitHub?'"
   puts "-" * 40
 
-  result = robot.run(message: "What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.")
+  result = robot.run("What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.")
 
   puts
   puts "Robot Response:"

data/examples/05_streaming.rb

@@ -8,13 +8,10 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/05_streaming.rb
 
-require_relative "../lib/robot_lab"
+# Configure template path before loading (MywayConfig reads env vars on init)
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
-  config.template_path = File.join(__dir__, "prompts")
-end
+require_relative "../lib/robot_lab"
 
 # Create a streaming handler
 streaming_handler = lambda do |event|
@@ -97,11 +94,11 @@ puts <<~CODE
   robot = RobotLab.build(
     name: "streamer",
     template: :helper,
-    model: "claude-sonnet-4"
+    model: "claude-3-haiku-20240307"
   )
 
   # Run with streaming callback
-  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/examples/06_prompt_templates.rb

@@ -1,29 +1,24 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Example 6: Prompt Templates with ruby_llm-template
+# Example 6: Prompt Templates with prompt_manager
 #
-# Demonstrates using ruby_llm-template for organized, reusable prompts
+# Demonstrates using prompt_manager for organized, reusable prompts
 # within a RobotLab network. This example shows an e-commerce support
 # system with dynamic context injection using SimpleFlow's optional task routing.
 #
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/06_prompt_templates.rb
 #
-# Template Structure:
+# Template Structure (prompt_manager .md files with YAML front matter):
 #   examples/prompts/
-#   ├── triage/
-#   │   ├── system.txt.erb
-#   │   └── user.txt.erb
-#   ├── order_support/
-#   │   ├── system.txt.erb
-#   │   └── user.txt.erb
-#   ├── product_support/
-#   │   ├── system.txt.erb
-#   │   └── user.txt.erb
-#   └── escalation/
-#       ├── system.txt.erb
-#       └── user.txt.erb
+#   ├── triage.md
+#   ├── order_support.md
+#   ├── product_support.md
+#   └── escalation.md
+
+# Configure template path before loading (MywayConfig reads env vars on init)
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
 
 require_relative "../lib/robot_lab"
 
@@ -31,8 +26,14 @@ require_relative "../lib/robot_lab"
 # Sample Data
 # =============================================================================
 # Simulated customer and business data that would come from your database.
+# company_name is a template parameter (declared null in all four templates).
+# AskUser gathers it from the user before building robots.
 
-COMPANY_NAME = "TechGear Pro"
+ask = RobotLab::AskUser.new
+COMPANY_NAME = ask.call(
+  "question" => "What is your company name?",
+  "default"  => "TechGear Pro"
+)
 
 SAMPLE_CUSTOMER = {
   name: "Sarah Johnson",
@@ -149,14 +150,16 @@ ESCALATION_AUTHORITIES = [
 # Custom triage robot that classifies and activates appropriate specialist
 class TriageRobot < RobotLab::Robot
   def call(result)
-    robot_result = run(**extract_run_context(result))
+    run_context = extract_run_context(result)
+    message = run_context.delete(:message)
+    robot_result = run(message, **run_context)
 
     new_result = result
       .with_context(@name.to_sym, robot_result)
       .continue(robot_result)
 
     # Examine LLM output and activate appropriate specialist
-    classification = robot_result.last_text_content.to_s.strip.downcase
+    classification = robot_result.reply.to_s.strip.downcase
 
     case classification
     when /order/
@@ -182,11 +185,7 @@ puts "E-Commerce Support Network with Dynamic Context"
 puts "=" * 70
 puts
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
-  config.template_path = File.join(__dir__, "prompts")
-end
+# Template path is set via ROBOT_LAB_TEMPLATE_PATH env var (see top of file)
 
 # -----------------------------------------------------------------------------
 # Build Robots with Template-Based Prompts
@@ -197,11 +196,12 @@ triage_robot = TriageRobot.new(
   name: "triage",
   description: "Classifies incoming requests to route to specialists",
   template: :triage,
+  local_tools: [RobotLab::AskUser],
   context: {
     company_name: COMPANY_NAME,
     categories: CATEGORIES
   },
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 # Order Support Robot
@@ -209,12 +209,13 @@ order_robot = RobotLab.build(
   name: "order",
   description: "Handles order-related inquiries with full order history",
   template: :order_support,
+  local_tools: [RobotLab::AskUser],
   context: {
     company_name: COMPANY_NAME,
     policies: POLICIES,
     capabilities: ORDER_CAPABILITIES
   },
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 # Product Support Robot
@@ -222,13 +223,14 @@ product_robot = RobotLab.build(
   name: "product",
   description: "Answers product questions with catalog knowledge",
   template: :product_support,
+  local_tools: [RobotLab::AskUser],
   context: {
     company_name: COMPANY_NAME,
     products: PRODUCTS,
     promotions: PROMOTIONS,
     product_categories: PRODUCT_CATEGORIES
   },
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 # Escalation Robot
@@ -236,11 +238,12 @@ escalation_robot = RobotLab.build(
   name: "escalation",
   description: "Handles complex cases requiring special authority",
   template: :escalation,
+  local_tools: [RobotLab::AskUser],
   context: {
     company_name: COMPANY_NAME,
     authorities: ESCALATION_AUTHORITIES
   },
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 # -----------------------------------------------------------------------------
@@ -291,14 +294,14 @@ demo_queries.each_with_index do |query, index|
   # Display triage classification
   if result.context[:triage]
     triage_result = result.context[:triage]
-    puts "Classification: #{triage_result.last_text_content}"
+    puts "Classification: #{triage_result.reply}"
     puts
   end
 
   # Display specialist response (the final value)
   if result.value.is_a?(RobotLab::RobotResult)
     puts "Routed to: #{result.value.robot_name.upcase}"
-    content = result.value.last_text_content.to_s
+    content = result.value.reply.to_s
     # Truncate long responses for display
     if content.length > 300
       puts "Response: #{content[0..300]}..."
@@ -314,11 +317,13 @@ end
 puts
 puts "Demo Complete!"
 puts
-puts "This example demonstrates:"
-puts "  - ruby_llm-template for organized, reusable prompts"
-puts "  - Build-time context (robot identity/capabilities)"
-puts "  - Run-time context (customer data, order history)"
-puts "  - Multi-robot network with optional task routing"
-puts "  - SimpleFlow::Result for passing context between robots"
-puts
-puts "Template files are located in: #{File.join(__dir__, 'prompts')}"
+puts <<~FOOTER
+  This example demonstrates:
+    - prompt_manager templates (.md with YAML front matter)
+    - Build-time context (robot identity/capabilities)
+    - Run-time context (customer data, order history)
+    - Multi-robot network with optional task routing
+    - SimpleFlow::Result for passing context between robots
+
+  Template files are located in: #{File.join(__dir__, 'prompts')}
+FOOTER

data/examples/07_network_memory.rb

@@ -41,15 +41,12 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/07_network_memory.rb
 
+# Configure template path before loading (MywayConfig reads env vars on init)
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+
 require_relative "../lib/robot_lab"
 require "json"
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
-  config.template_path = File.join(__dir__, "prompts")
-end
-
 puts "=" * 60
 puts "Example 7: Network Memory with Concurrent Robots"
 puts "=" * 60
@@ -69,12 +66,13 @@ class AnalysisRobot < RobotLab::Robot
   def call(result)
     run_context = extract_run_context(result)
     network_memory = run_context.delete(:network_memory)
+    message = run_context.delete(:message)
 
-    robot_result = run(network_memory: network_memory, **run_context)
+    robot_result = run(message, network_memory: network_memory, **run_context)
 
     # Parse the JSON response and write to shared memory
     if network_memory
-      content = robot_result.last_text_content.to_s
+      content = robot_result.reply.to_s
 
       # Set writer before writing to memory
       network_memory.current_writer = @name
@@ -101,6 +99,7 @@ class SynthesizerRobot < RobotLab::Robot
   def call(result)
     run_context = extract_run_context(result)
     network_memory = run_context.delete(:network_memory)
+    message = run_context.delete(:message)
 
     puts "  [#{@name}] Reading analysis results from memory..."
 
@@ -125,7 +124,7 @@ class SynthesizerRobot < RobotLab::Robot
       run_context[:keywords] = "Not available"
     end
 
-    robot_result = run(network_memory: network_memory, **run_context)
+    robot_result = run(message, network_memory: network_memory, **run_context)
 
     result
       .with_context(@name.to_sym, robot_result)
@@ -154,27 +153,27 @@ sentiment_robot = AnalysisRobot.new(
   name: "sentiment_analyzer",
   template: :sentiment_analyzer,
   memory_key: :sentiment,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 entity_robot = AnalysisRobot.new(
   name: "entity_extractor",
   template: :entity_extractor,
   memory_key: :entities,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 keyword_robot = AnalysisRobot.new(
   name: "keyword_extractor",
   template: :keyword_extractor,
   memory_key: :keywords,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 synthesizer = SynthesizerRobot.new(
   name: "synthesizer",
   template: :synthesizer,
-  model: "claude-sonnet-4"
+  model: "claude-3-haiku-20240307"
 )
 
 # -----------------------------------------------------------------------------
@@ -267,7 +266,7 @@ puts "=" * 60
 puts
 
 if result.value.is_a?(RobotLab::RobotResult)
-  puts result.value.last_text_content
+  puts result.value.reply
 end
 
 puts