robot_lab 0.0.1

data/examples/07_network_memory.rb

@@ -0,0 +1,329 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 7: Network Memory with Concurrent Robots
+#
+# Demonstrates the reactive shared memory system where:
+# - Multiple robots run concurrently and write to shared memory
+# - Robots can wait for values written by other robots
+# - Subscriptions provide real-time notifications of memory changes
+# - Network broadcast sends messages to all robots
+#
+# Architecture:
+#   ┌─────────────────────────────────────────────────────────────┐
+#   │                    PARALLEL ANALYSIS                         │
+#   │                                                              │
+#   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+#   │  │  Sentiment  │  │  Entities   │  │  Keywords   │         │
+#   │  │  Analyzer   │  │  Extractor  │  │  Extractor  │         │
+#   │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
+#   │         │                │                │                 │
+#   │         ▼                ▼                ▼                 │
+#   │  memory.set(       memory.set(      memory.set(            │
+#   │   :sentiment)       :entities)       :keywords)            │
+#   │         │                │                │                 │
+#   │         └────────────────┼────────────────┘                 │
+#   │                          ▼                                  │
+#   │  ┌──────────────────────────────────────────────────────┐  │
+#   │  │                  SHARED MEMORY                        │  │
+#   │  │  { sentiment: {...}, entities: {...}, keywords: {...} │  │
+#   │  └──────────────────────────────────────────────────────┘  │
+#   │                          │                                  │
+#   │                          ▼                                  │
+#   │  ┌──────────────────────────────────────────────────────┐  │
+#   │  │                   Synthesizer                         │  │
+#   │  │    memory.get(:sentiment, :entities, :keywords,       │  │
+#   │  │               wait: true)                             │  │
+#   │  └──────────────────────────────────────────────────────┘  │
+#   │                                                              │
+#   └─────────────────────────────────────────────────────────────┘
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/07_network_memory.rb
+
+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
+puts
+
+# -----------------------------------------------------------------------------
+# Custom Robot Classes that Write to Shared Memory
+# -----------------------------------------------------------------------------
+
+# Base class for analysis robots that write results to memory
+class AnalysisRobot < RobotLab::Robot
+  def initialize(memory_key:, **opts)
+    super(**opts)
+    @memory_key = memory_key
+  end
+
+  def call(result)
+    run_context = extract_run_context(result)
+    network_memory = run_context.delete(:network_memory)
+
+    robot_result = run(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
+
+      # Set writer before writing to memory
+      network_memory.current_writer = @name
+
+      begin
+        parsed = JSON.parse(content)
+        network_memory.set(@memory_key, parsed)
+        puts "  [#{@name}] Wrote JSON to memory[:#{@memory_key}]"
+      rescue JSON::ParserError
+        # If not valid JSON, store the raw text
+        network_memory.set(@memory_key, content)
+        puts "  [#{@name}] Wrote text to memory[:#{@memory_key}]"
+      end
+    end
+
+    result
+      .with_context(@name.to_sym, robot_result)
+      .continue(robot_result)
+  end
+end
+
+# Synthesizer robot that reads from shared memory and synthesizes results
+class SynthesizerRobot < RobotLab::Robot
+  def call(result)
+    run_context = extract_run_context(result)
+    network_memory = run_context.delete(:network_memory)
+
+    puts "  [#{@name}] Reading analysis results from memory..."
+
+    if network_memory
+      # Read results from memory - they should already be there since
+      # SimpleFlow ensures our dependencies completed first
+      sentiment = network_memory.get(:sentiment)
+      entities = network_memory.get(:entities)
+      keywords = network_memory.get(:keywords)
+
+      puts "  [#{@name}] Got sentiment: #{sentiment.nil? ? 'nil' : 'present'}"
+      puts "  [#{@name}] Got entities: #{entities.nil? ? 'nil' : 'present'}"
+      puts "  [#{@name}] Got keywords: #{keywords.nil? ? 'nil' : 'present'}"
+
+      # Format for the template
+      run_context[:sentiment] = format_for_template(sentiment)
+      run_context[:entities] = format_for_template(entities)
+      run_context[:keywords] = format_for_template(keywords)
+    else
+      run_context[:sentiment] = "Not available"
+      run_context[:entities] = "Not available"
+      run_context[:keywords] = "Not available"
+    end
+
+    robot_result = run(network_memory: network_memory, **run_context)
+
+    result
+      .with_context(@name.to_sym, robot_result)
+      .continue(robot_result)
+  end
+
+  private
+
+  def format_for_template(value)
+    case value
+    when Hash, Array
+      JSON.pretty_generate(value)
+    when nil
+      "Not available"
+    else
+      value.to_s
+    end
+  end
+end
+
+# -----------------------------------------------------------------------------
+# Create the Robots
+# -----------------------------------------------------------------------------
+
+sentiment_robot = AnalysisRobot.new(
+  name: "sentiment_analyzer",
+  template: :sentiment_analyzer,
+  memory_key: :sentiment,
+  model: "claude-sonnet-4"
+)
+
+entity_robot = AnalysisRobot.new(
+  name: "entity_extractor",
+  template: :entity_extractor,
+  memory_key: :entities,
+  model: "claude-sonnet-4"
+)
+
+keyword_robot = AnalysisRobot.new(
+  name: "keyword_extractor",
+  template: :keyword_extractor,
+  memory_key: :keywords,
+  model: "claude-sonnet-4"
+)
+
+synthesizer = SynthesizerRobot.new(
+  name: "synthesizer",
+  template: :synthesizer,
+  model: "claude-sonnet-4"
+)
+
+# -----------------------------------------------------------------------------
+# Create the Network with Shared Memory
+# -----------------------------------------------------------------------------
+
+network = RobotLab.create_network(name: "parallel_analysis") do
+  # Three analysis robots run in parallel (all depend on nothing)
+  task :sentiment, sentiment_robot, depends_on: :none
+  task :entities, entity_robot, depends_on: :none
+  task :keywords, keyword_robot, depends_on: :none
+
+  # Synthesizer waits for all three to complete
+  task :synthesize, synthesizer, depends_on: [:sentiment, :entities, :keywords]
+end
+
+# -----------------------------------------------------------------------------
+# Set Up Memory Subscriptions (for monitoring)
+# -----------------------------------------------------------------------------
+
+puts "Setting up memory subscriptions for monitoring..."
+puts
+
+# Note: In concurrent execution, change.writer may be unreliable due to race
+# conditions. For production use, consider including writer info in the value.
+network.memory.subscribe(:sentiment, :entities, :keywords) do |change|
+  value_preview = case change.value
+                  when Hash then change.value.keys.join(", ")
+                  when String then change.value[0..50]
+                  else change.value.class.name
+                  end
+  puts "  [MONITOR] Memory[:#{change.key}] updated with keys: #{value_preview}"
+end
+
+# -----------------------------------------------------------------------------
+# Set Up Broadcast Handler
+# -----------------------------------------------------------------------------
+
+network.on_broadcast do |message|
+  puts "  [BROADCAST] #{message[:payload][:event]}: #{message[:payload][:details]}"
+end
+
+# -----------------------------------------------------------------------------
+# Run the Network
+# -----------------------------------------------------------------------------
+
+sample_text = <<~TEXT
+  Apple Inc. announced today that CEO Tim Cook will be presenting the new iPhone 15
+  at their headquarters in Cupertino, California on September 12th, 2024.
+  Industry analysts are extremely excited about the new features, though some
+  consumer advocates have expressed concerns about the expected price increase.
+  Samsung and Google are reportedly preparing competitive responses for later this year.
+TEXT
+
+puts "Network structure:"
+puts network.visualize
+puts
+puts "-" * 60
+puts "Input text:"
+puts sample_text.strip
+puts "-" * 60
+puts
+
+# Send a broadcast before starting
+network.broadcast(event: "analysis_started", details: "Beginning parallel analysis")
+
+puts "Running parallel analysis..."
+puts
+start_time = Time.now
+
+result = network.run(message: sample_text)
+
+elapsed = Time.now - start_time
+puts
+puts "-" * 60
+puts "Analysis complete in #{elapsed.round(2)} seconds"
+puts "-" * 60
+
+# Send completion broadcast
+network.broadcast(event: "analysis_complete", details: "All robots finished")
+
+# -----------------------------------------------------------------------------
+# Display Results
+# -----------------------------------------------------------------------------
+
+puts
+puts "=" * 60
+puts "FINAL SYNTHESIS"
+puts "=" * 60
+puts
+
+if result.value.is_a?(RobotLab::RobotResult)
+  puts result.value.last_text_content
+end
+
+puts
+puts "=" * 60
+puts "MEMORY STATE"
+puts "=" * 60
+puts
+
+# Show what's in shared memory
+memory = network.memory
+puts "Sentiment: #{memory.get(:sentiment)&.to_json}"
+puts
+puts "Entities: #{memory.get(:entities)&.to_json}"
+puts
+puts "Keywords: #{memory.get(:keywords)&.to_json}"
+
+# -----------------------------------------------------------------------------
+# Demonstrate Blocking Wait (without pipeline dependencies)
+# -----------------------------------------------------------------------------
+
+puts
+puts "=" * 60
+puts "DEMONSTRATING BLOCKING WAIT"
+puts "=" * 60
+puts
+
+# Create a fresh memory for this demo
+demo_memory = RobotLab::Memory.new(network_name: "wait_demo")
+
+# Simulate a concurrent scenario where one thread waits for another
+puts "Starting writer thread (will write after 1 second)..."
+puts "Starting reader thread (will wait for value)..."
+
+reader_result = nil
+writer_done = false
+
+reader = Thread.new do
+  start = Time.now
+  puts "  [reader] Waiting for :delayed_result..."
+  value = demo_memory.get(:delayed_result, wait: 10)
+  elapsed = Time.now - start
+  reader_result = value
+  puts "  [reader] Got value after #{elapsed.round(2)}s: #{value}"
+end
+
+writer = Thread.new do
+  sleep 1
+  demo_memory.set(:delayed_result, { status: "complete", data: [1, 2, 3] })
+  writer_done = true
+  puts "  [writer] Wrote :delayed_result to memory"
+end
+
+# Wait for both threads
+writer.join
+reader.join
+
+puts
+puts "Blocking wait demonstration complete!"
+puts "Reader received: #{reader_result.inspect}"

data/examples/prompts/assistant/system.txt.erb

@@ -0,0 +1,2 @@
+You are a helpful assistant with access to tools.
+Use the calculator for math and fortune_cookie for fortune requests.

data/examples/prompts/assistant/user.txt.erb

@@ -0,0 +1 @@
+<%= message %>

data/examples/prompts/billing/system.txt.erb

@@ -0,0 +1,7 @@
+You are a billing support specialist. Help users with:
+- Invoice questions
+- Payment issues
+- Subscription management
+- Refunds
+
+Be professional and helpful.

data/examples/prompts/billing/user.txt.erb

@@ -0,0 +1 @@
+<%= message %>

data/examples/prompts/classifier/system.txt.erb

@@ -0,0 +1,4 @@
+You are a request classifier. Analyze the user's request and classify it
+as either "billing", "technical", or "general".
+
+Respond with ONLY the category name, nothing else.

data/examples/prompts/classifier/user.txt.erb

@@ -0,0 +1 @@
+<%= message %>

data/examples/prompts/entity_extractor/system.txt.erb

@@ -0,0 +1,11 @@
+You are an entity extraction expert. Your job is to identify named entities in text.
+
+Analyze the given text and respond with a JSON object containing:
+- people: array of person names mentioned
+- organizations: array of company/organization names
+- locations: array of place names
+- products: array of product/service names
+- dates: array of date/time references
+- other: array of other notable entities
+
+Respond ONLY with the JSON object, no additional text.

data/examples/prompts/entity_extractor/user.txt.erb

@@ -0,0 +1,3 @@
+Extract all named entities from this text:
+
+<%= message %>

data/examples/prompts/escalation/system.txt.erb

@@ -0,0 +1,35 @@
+You are a senior customer experience specialist for <%= company_name %>, handling escalated and complex cases.
+
+## Your Role
+You handle situations that require:
+- Special authorization or exceptions
+- Complex multi-issue resolutions
+- Sensitive customer situations
+- Cases requiring human judgment
+
+## Escalation Authorities
+<% authorities.each do |auth| %>
+- **<%= auth[:name] %>**: <%= auth[:description] %> (Limit: <%= auth[:limit] %>)
+<% end %>
+
+## Customer Information
+- Name: <%= customer[:name] %>
+- Account Type: <%= customer[:account_type] %>
+- Customer Since: <%= customer[:member_since] %>
+- Lifetime Value: $<%= customer[:lifetime_value] %>
+<% if customer[:vip] %>
+- VIP Status: Yes
+<% end %>
+<% if customer[:escalation_history]&.any? %>
+- Previous Escalations: <%= customer[:escalation_history].count %>
+<% end %>
+
+## Guidelines
+1. Acknowledge the customer's frustration immediately
+2. Take ownership of the issue
+3. Explain what you CAN do, not what you can't
+4. Use your authorities to resolve issues when justified
+5. If truly beyond scope, prepare a detailed handoff for human agents
+6. Document all actions and decisions
+
+Your goal is to turn a frustrated customer into a loyal advocate.

data/examples/prompts/escalation/user.txt.erb

@@ -0,0 +1,34 @@
+Customer <%= customer[:name] %> (escalated case): <%= message %>
+
+## Case Context
+<% if defined?(escalation_context) && escalation_context %>
+<% if escalation_context[:previous_interactions]&.any? %>
+### Previous Interactions
+<% escalation_context[:previous_interactions].each do |interaction| %>
+- <%= interaction[:date] %> (<%= interaction[:channel] %>): <%= interaction[:summary] %>
+<% end %>
+<% end %>
+
+<% if escalation_context[:related_orders]&.any? %>
+### Related Orders
+<% escalation_context[:related_orders].each do |order| %>
+- Order #<%= order[:id] %>: $<%= order[:total] %> - <%= order[:status] %>
+<% end %>
+<% end %>
+
+<% if escalation_context[:compensation_history]&.any? %>
+### Previous Compensation
+<% escalation_context[:compensation_history].each do |comp| %>
+- <%= comp[:date] %>: <%= comp[:type] %> - $<%= comp[:amount] %> (<%= comp[:reason] %>)
+<% end %>
+<% end %>
+
+### Escalation Reason
+<%= escalation_context[:escalation_reason] || "Not specified" %>
+
+### Sentiment Analysis
+- Detected Sentiment: <%= escalation_context[:sentiment] || "Unknown" %>
+- Urgency Level: <%= escalation_context[:urgency] || "Normal" %>
+<% end %>
+
+Please resolve this escalated case with empathy and authority.

data/examples/prompts/general/system.txt.erb

@@ -0,0 +1,4 @@
+You are a general support robot. Help users with any questions
+that don't fit into billing or technical categories.
+
+Be friendly and helpful.

data/examples/prompts/general/user.txt.erb

@@ -0,0 +1 @@
+<%= message %>

data/examples/prompts/github_assistant/system.txt.erb

@@ -0,0 +1,6 @@
+You are a helpful GitHub assistant with access to GitHub tools via MCP.
+
+You can search repositories, view issues, read file contents, and more.
+Use the available tools to help answer questions about GitHub repositories.
+
+Be concise and provide relevant information from the tools when needed.

data/examples/prompts/github_assistant/user.txt.erb

@@ -0,0 +1 @@
+<%= message %>

data/examples/prompts/helper/system.txt.erb

@@ -0,0 +1 @@
+You are a helpful assistant. Be concise and friendly in your responses.

data/examples/prompts/helper/user.txt.erb

@@ -0,0 +1 @@
+<%= message %>

data/examples/prompts/keyword_extractor/system.txt.erb

@@ -0,0 +1,8 @@
+You are a keyword extraction expert. Your job is to identify the most important keywords and topics in text.
+
+Analyze the given text and respond with a JSON object containing:
+- keywords: array of the top 5-10 most important keywords/phrases
+- topics: array of 2-3 main topics or themes
+- category: the primary category (e.g., "technology", "business", "health", "entertainment")
+
+Respond ONLY with the JSON object, no additional text.

data/examples/prompts/keyword_extractor/user.txt.erb

@@ -0,0 +1,3 @@
+Extract keywords and topics from this text:
+
+<%= message %>

data/examples/prompts/order_support/system.txt.erb

@@ -0,0 +1,27 @@
+You are a friendly and efficient order support specialist for <%= company_name %>.
+
+## Your Capabilities
+<% capabilities.each do |capability| %>
+- <%= capability %>
+<% end %>
+
+## Policies
+- Refunds: <%= policies[:refund_window] %> day window for returns
+- Shipping: Free shipping on orders over $<%= policies[:free_shipping_threshold] %>
+- Express Processing: Available for <%= policies[:express_fee] %> extra
+
+## Customer Information
+- Name: <%= customer[:name] %>
+- Account Type: <%= customer[:account_type] %>
+<% if customer[:vip] %>
+- VIP Customer: Apply priority handling and extended policies
+<% end %>
+
+## Guidelines
+1. Always greet the customer by name
+2. Reference specific order numbers when discussing issues
+3. Offer solutions, not just explanations
+4. If a refund is appropriate, process it proactively
+5. For VIP customers, be extra accommodating
+
+Be helpful, empathetic, and solution-oriented.

data/examples/prompts/order_support/user.txt.erb

@@ -0,0 +1,22 @@
+Customer <%= customer[:name] %> asks: <%= message %>
+
+## Order History
+<% if orders&.any? %>
+<% orders.each do |order| %>
+### Order #<%= order[:id] %>
+- Date: <%= order[:date] %>
+- Status: <%= order[:status] %>
+- Total: $<%= order[:total] %>
+- Items:
+<% order[:items].each do |item| %>
+  - <%= item[:name] %> (x<%= item[:quantity] %>) - $<%= item[:price] %>
+<% end %>
+<% if order[:tracking] %>
+- Tracking: <%= order[:tracking] %>
+<% end %>
+<% end %>
+<% else %>
+No orders found for this customer.
+<% end %>
+
+Please help the customer with their order inquiry.

data/examples/prompts/product_support/system.txt.erb

@@ -0,0 +1,30 @@
+You are a knowledgeable product specialist for <%= company_name %>.
+
+## Your Expertise
+You have deep knowledge of our product catalog and can help customers with:
+- Product features and specifications
+- Compatibility questions
+- Usage recommendations
+- Product comparisons
+- Availability and restocking information
+
+## Product Categories We Carry
+<% product_categories.each do |category| %>
+- **<%= category[:name] %>**: <%= category[:description] %>
+<% end %>
+
+## Customer Context
+- Name: <%= customer[:name] %>
+- Account Type: <%= customer[:account_type] %>
+<% if customer[:purchase_history]&.any? %>
+- Previous Purchases: <%= customer[:purchase_history].map { |p| p[:category] }.uniq.join(", ") %>
+<% end %>
+
+## Guidelines
+1. Provide accurate, detailed product information
+2. Make personalized recommendations based on their history
+3. If a product is out of stock, suggest alternatives
+4. Highlight any current promotions or bundles
+5. Be enthusiastic but honest about product capabilities
+
+Help the customer find the perfect product for their needs.

data/examples/prompts/product_support/user.txt.erb

@@ -0,0 +1,32 @@
+Customer <%= customer[:name] %> asks: <%= message %>
+
+## Relevant Products
+<% if products&.any? %>
+<% products.each do |product| %>
+### <%= product[:name] %>
+- SKU: <%= product[:sku] %>
+- Price: $<%= product[:price] %>
+- Category: <%= product[:category] %>
+- In Stock: <%= product[:in_stock] ? "Yes (#{product[:quantity]} available)" : "No" %>
+<% if product[:features]&.any? %>
+- Features:
+<% product[:features].each do |feature| %>
+  - <%= feature %>
+<% end %>
+<% end %>
+<% if product[:compatible_with]&.any? %>
+- Compatible With: <%= product[:compatible_with].join(", ") %>
+<% end %>
+<% end %>
+<% else %>
+No specific products matched the query. Provide general guidance.
+<% end %>
+
+<% if promotions&.any? %>
+## Current Promotions
+<% promotions.each do |promo| %>
+- **<%= promo[:name] %>**: <%= promo[:description] %> (Code: <%= promo[:code] %>)
+<% end %>
+<% end %>
+
+Please help the customer with their product question.

data/examples/prompts/sentiment_analyzer/system.txt.erb

@@ -0,0 +1,9 @@
+You are a sentiment analysis expert. Your job is to analyze the emotional tone of text.
+
+Analyze the given text and respond with a JSON object containing:
+- score: a number from -1.0 (very negative) to 1.0 (very positive)
+- confidence: a number from 0.0 to 1.0 indicating your confidence
+- primary_emotion: the dominant emotion (e.g., "joy", "anger", "sadness", "fear", "surprise", "neutral")
+- summary: a brief one-sentence explanation
+
+Respond ONLY with the JSON object, no additional text.

data/examples/prompts/sentiment_analyzer/user.txt.erb

@@ -0,0 +1,3 @@
+Analyze the sentiment of this text:
+
+<%= message %>

data/examples/prompts/synthesizer/system.txt.erb

@@ -0,0 +1,14 @@
+You are a content synthesis expert. Your job is to combine analysis results from multiple sources into a coherent summary.
+
+You will receive:
+- Sentiment analysis results
+- Entity extraction results
+- Keyword extraction results
+
+Create a comprehensive summary that:
+1. Describes the overall tone and emotional context
+2. Highlights key entities and their relationships
+3. Identifies the main themes and topics
+4. Provides actionable insights or recommendations
+
+Be concise but thorough.

data/examples/prompts/synthesizer/user.txt.erb

@@ -0,0 +1,15 @@
+Please synthesize these analysis results into a comprehensive summary:
+
+## Original Text
+<%= message %>
+
+## Sentiment Analysis
+<%= sentiment %>
+
+## Entities Found
+<%= entities %>
+
+## Keywords & Topics
+<%= keywords %>
+
+Provide a unified analysis combining all these perspectives.

data/examples/prompts/technical/system.txt.erb

@@ -0,0 +1,7 @@
+You are a technical support specialist. Help users with:
+- Bug reports
+- Feature questions
+- Integration help
+- Troubleshooting
+
+Be technical but clear.

data/examples/prompts/technical/user.txt.erb

@@ -0,0 +1 @@
+<%= message %>