flow_nodes 0.1.0

data/examples/advanced_workflow.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require_relative "../lib/flow_nodes"
+require "securerandom"
+
+# This example demonstrates:
+# 1. Full lifecycle hooks (prep, exec, post)
+# 2. Symbol-based actions (preferred over strings)
+# 3. State management across nodes
+# 4. Error handling with retries
+# 5. Conditional branching
+
+module AdvancedWorkflow
+  class OrderValidationNode < FlowNodes::Node
+    def initialize
+      super(max_retries: 2, wait: 0.5)
+    end
+
+    def prep(state)
+      puts "🔍 [#{Time.now.strftime('%H:%M:%S')}] Starting order validation..."
+      state[:validation_start] = Time.now
+      state[:order_id] = SecureRandom.hex(6)
+      
+      # Add validation metadata to params
+      @params.merge({
+        validation_id: SecureRandom.hex(4),
+        validated_at: Time.now
+      })
+    end
+
+    def exec(order_data)
+      puts "📝 [#{Time.now.strftime('%H:%M:%S')}] Validating order #{order_data[:validation_id]}..."
+      
+      # Simulate validation checks
+      return :missing_customer if !order_data[:customer_id]
+      return :invalid_items if !order_data[:items] || order_data[:items].empty?
+      return :invalid_total if !order_data[:total] || order_data[:total] <= 0
+      
+      # Simulate network failure for retry demo
+      if rand < 0.3
+        raise StandardError, "Validation service timeout"
+      end
+      
+      :valid_order
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:validation_start]
+      puts "✅ [#{Time.now.strftime('%H:%M:%S')}] Validation completed in #{duration.round(3)}s: #{result}"
+      
+      state[:validation_result] = result
+      state[:validation_duration] = duration
+    end
+
+    def exec_fallback(params, exception)
+      puts "⚠️  [#{Time.now.strftime('%H:%M:%S')}] Validation failed after retries: #{exception.message}"
+      :validation_failed
+    end
+  end
+
+  class InventoryCheckNode < FlowNodes::Node
+    def prep(state)
+      puts "📦 [#{Time.now.strftime('%H:%M:%S')}] Checking inventory..."
+      state[:inventory_check_start] = Time.now
+      nil
+    end
+
+    def exec(order_data)
+      puts "🔍 [#{Time.now.strftime('%H:%M:%S')}] Checking #{order_data[:items].length} items..."
+      
+      # Simulate inventory check
+      order_data[:items].each do |item|
+        puts "   - #{item[:name]}: #{item[:quantity]} units"
+      end
+      
+      sleep(0.1) # Simulate processing time
+      
+      # Simulate out of stock scenario
+      if order_data[:items].any? { |item| item[:quantity] > 10 }
+        return :out_of_stock
+      end
+      
+      :inventory_available
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:inventory_check_start]
+      puts "✅ [#{Time.now.strftime('%H:%M:%S')}] Inventory check completed: #{result}"
+      
+      state[:inventory_result] = result
+      state[:inventory_duration] = duration
+    end
+  end
+
+  class PaymentProcessingNode < FlowNodes::Node
+    def prep(state)
+      puts "💳 [#{Time.now.strftime('%H:%M:%S')}] Processing payment..."
+      state[:payment_start] = Time.now
+      
+      # Add payment metadata
+      @params.merge({
+        payment_id: SecureRandom.hex(8),
+        processor: "stripe"
+      })
+    end
+
+    def exec(order_data)
+      puts "💰 [#{Time.now.strftime('%H:%M:%S')}] Processing $#{order_data[:total]} payment..."
+      puts "📊 Payment ID: #{order_data[:payment_id]}"
+      
+      # Simulate payment processing
+      sleep(0.2)
+      
+      # Simulate payment failure
+      if order_data[:total] > 1000
+        return :payment_declined
+      end
+      
+      :payment_successful
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:payment_start]
+      puts "✅ [#{Time.now.strftime('%H:%M:%S')}] Payment processing completed: #{result}"
+      
+      state[:payment_result] = result
+      state[:payment_duration] = duration
+    end
+  end
+
+  class OrderFulfillmentNode < FlowNodes::Node
+    def prep(state)
+      puts "🚚 [#{Time.now.strftime('%H:%M:%S')}] Starting order fulfillment..."
+      state[:fulfillment_start] = Time.now
+      
+      @params.merge({
+        tracking_id: SecureRandom.hex(10),
+        estimated_delivery: Time.now + (3 * 24 * 60 * 60) # 3 days
+      })
+    end
+
+    def exec(order_data)
+      puts "📦 [#{Time.now.strftime('%H:%M:%S')}] Fulfilling order..."
+      puts "📊 Tracking ID: #{order_data[:tracking_id]}"
+      puts "🚚 Estimated delivery: #{order_data[:estimated_delivery].strftime('%Y-%m-%d')}"
+      
+      # Simulate fulfillment
+      sleep(0.1)
+      
+      :order_shipped
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:fulfillment_start]
+      puts "✅ [#{Time.now.strftime('%H:%M:%S')}] Order fulfilled in #{duration.round(3)}s"
+      
+      state[:fulfillment_result] = result
+      state[:fulfillment_duration] = duration
+    end
+  end
+
+  class ErrorHandlerNode < FlowNodes::Node
+    def prep(state)
+      puts "🚨 [#{Time.now.strftime('%H:%M:%S')}] Handling error condition..."
+      state[:error_start] = Time.now
+      nil
+    end
+
+    def exec(order_data)
+      error_type = @params[:error_type] || "unknown_error"
+      puts "❌ [#{Time.now.strftime('%H:%M:%S')}] Error: #{error_type}"
+      puts "📊 Order ID: #{order_data[:validation_id] || 'N/A'}"
+      
+      # Log error for monitoring
+      puts "📋 Error logged for investigation"
+      
+      :error_handled
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:error_start]
+      puts "🔧 [#{Time.now.strftime('%H:%M:%S')}] Error handling completed in #{duration.round(3)}s"
+      
+      state[:error_handled] = true
+      state[:error_duration] = duration
+    end
+  end
+
+  class CompletionNode < FlowNodes::Node
+    def prep(state)
+      puts "🎯 [#{Time.now.strftime('%H:%M:%S')}] Finalizing order..."
+      state[:completion_start] = Time.now
+      nil
+    end
+
+    def exec(order_data)
+      puts "🎉 [#{Time.now.strftime('%H:%M:%S')}] Order completed successfully!"
+      puts "📊 Final order data:"
+      puts "   - Order ID: #{order_data[:validation_id] || 'N/A'}"
+      puts "   - Payment ID: #{order_data[:payment_id] || 'N/A'}"
+      puts "   - Tracking ID: #{order_data[:tracking_id] || 'N/A'}"
+      puts "   - Total: $#{order_data[:total] || 'N/A'}"
+      
+      nil # End flow
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:completion_start]
+      
+      puts "✅ [#{Time.now.strftime('%H:%M:%S')}] Order workflow completed!"
+      puts "📊 Performance metrics:"
+      if state[:validation_start]
+        total_duration = Time.now - state[:validation_start]
+        puts "   - Total time: #{total_duration.round(3)}s"
+      end
+      puts "   - Validation: #{state[:validation_duration]&.round(3)}s"
+      puts "   - Inventory: #{state[:inventory_duration]&.round(3)}s"
+      puts "   - Payment: #{state[:payment_duration]&.round(3)}s"
+      puts "   - Fulfillment: #{state[:fulfillment_duration]&.round(3)}s"
+    end
+  end
+end
+
+# Demo script
+if $PROGRAM_NAME == __FILE__
+  # Create nodes
+  validator = AdvancedWorkflow::OrderValidationNode.new
+  inventory = AdvancedWorkflow::InventoryCheckNode.new
+  payment = AdvancedWorkflow::PaymentProcessingNode.new
+  fulfillment = AdvancedWorkflow::OrderFulfillmentNode.new
+  error_handler = AdvancedWorkflow::ErrorHandlerNode.new
+  completion = AdvancedWorkflow::CompletionNode.new
+
+  # Connect workflow with symbol-based actions
+  validator - :valid_order >> inventory
+  validator - :missing_customer >> error_handler
+  validator - :invalid_items >> error_handler
+  validator - :invalid_total >> error_handler
+  validator - :validation_failed >> error_handler
+  
+  inventory - :inventory_available >> payment
+  inventory - :out_of_stock >> error_handler
+  
+  payment - :payment_successful >> fulfillment
+  payment - :payment_declined >> error_handler
+  
+  fulfillment - :order_shipped >> completion
+
+  # Create flow
+  flow = FlowNodes::Flow.new(start: validator)
+
+  # Test scenarios
+  puts "=" * 60
+  puts "🛒 E-COMMERCE ORDER PROCESSING WORKFLOW"
+  puts "=" * 60
+
+  # Scenario 1: Successful order
+  puts "\n📋 SCENARIO 1: Successful Order"
+  puts "-" * 40
+  state = { session_id: SecureRandom.hex(4) }
+  flow.set_params({
+    customer_id: "cust_123",
+    items: [
+      { name: "Widget A", quantity: 2, price: 29.99 },
+      { name: "Widget B", quantity: 1, price: 19.99 }
+    ],
+    total: 79.97
+  })
+  flow.run(state)
+
+  # Scenario 2: Out of stock
+  puts "\n📋 SCENARIO 2: Out of Stock"
+  puts "-" * 40
+  state = { session_id: SecureRandom.hex(4) }
+  flow.set_params({
+    customer_id: "cust_456",
+    items: [
+      { name: "Popular Item", quantity: 15, price: 49.99 }
+    ],
+    total: 49.99
+  })
+  flow.run(state)
+
+  # Scenario 3: Invalid order
+  puts "\n📋 SCENARIO 3: Invalid Order (Missing Customer)"
+  puts "-" * 40
+  state = { session_id: SecureRandom.hex(4) }
+  flow.set_params({
+    items: [
+      { name: "Widget C", quantity: 1, price: 39.99 }
+    ],
+    total: 39.99
+  })
+  flow.run(state)
+
+  puts "\n" + "=" * 60
+  puts "🎯 WORKFLOW DEMONSTRATIONS COMPLETE"
+  puts "=" * 60
+end

data/examples/batch_processing.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../lib/flow_nodes"
+
+module BatchDemo
+  class DataTransformNode < FlowNodes::BatchNode
+    def exec(item)
+      puts "Processing item: #{item}"
+      # Simulate some processing time
+      sleep(0.01)
+      
+      # Transform the data
+      {
+        original: item,
+        processed: item.to_s.upcase,
+        timestamp: Time.now
+      }
+    end
+  end
+
+  class AsyncDataTransformNode < FlowNodes::AsyncBatchNode
+    def exec_async(item)
+      puts "Async processing item: #{item}"
+      # Simulate async processing time
+      sleep(0.01)
+      
+      # Transform the data
+      {
+        original: item,
+        processed: item.to_s.upcase,
+        timestamp: Time.now,
+        thread_id: Thread.current.object_id
+      }
+    end
+  end
+
+  class ParallelDataTransformNode < FlowNodes::AsyncParallelBatchNode
+    def exec_async(item)
+      puts "Parallel processing item: #{item} on thread #{Thread.current.object_id}"
+      # Simulate processing time
+      sleep(0.1)
+      
+      # Transform the data
+      {
+        original: item,
+        processed: item.to_s.upcase,
+        timestamp: Time.now,
+        thread_id: Thread.current.object_id
+      }
+    end
+  end
+
+  class BatchCollectorFlow < FlowNodes::BatchFlow
+    def prep(state)
+      state[:results] = []
+      [1, 2, 3, 4, 5] # Return batch items
+    end
+
+    def post(state, prep_result, exec_result)
+      puts "Batch processing completed!"
+      puts "Results stored in state: #{state[:results].length} items"
+    end
+  end
+
+  class ResultCollectorNode < FlowNodes::Node
+    def exec(processed_item)
+      puts "Collecting result: #{processed_item}"
+      nil # End the flow for each item
+    end
+  end
+end
+
+# Demo script
+if $PROGRAM_NAME == __FILE__
+  puts "=== Sequential Batch Processing ==="
+  transformer = BatchDemo::DataTransformNode.new
+  transformer.set_params([1, 2, 3, 4, 5])
+  results = transformer.run(nil)
+  puts "Sequential results: #{results}"
+
+  puts "\n=== Async Sequential Batch Processing ==="
+  async_transformer = BatchDemo::AsyncDataTransformNode.new
+  async_transformer.set_params([1, 2, 3, 4, 5])
+  start_time = Time.now
+  results = async_transformer.run_async(nil)
+  end_time = Time.now
+  puts "Async sequential results: #{results}"
+  puts "Time taken: #{end_time - start_time} seconds"
+
+  puts "\n=== Parallel Batch Processing ==="
+  parallel_transformer = BatchDemo::ParallelDataTransformNode.new
+  parallel_transformer.set_params([1, 2, 3, 4, 5])
+  start_time = Time.now
+  results = parallel_transformer.run_async(nil)
+  end_time = Time.now
+  puts "Parallel results: #{results}"
+  puts "Time taken: #{end_time - start_time} seconds"
+  puts "Notice different thread IDs showing parallel execution"
+
+  puts "\n=== Batch Flow Example ==="
+  transformer = BatchDemo::DataTransformNode.new
+  collector = BatchDemo::ResultCollectorNode.new
+  
+  transformer >> collector
+  
+  flow = BatchDemo::BatchCollectorFlow.new(start: transformer)
+  flow.run({ results: [] })
+end

data/examples/chatbot.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../lib/flow_nodes"
+require "securerandom"
+
+module ChatDemo
+  # Simple utility to simulate an LLM call
+  module Utils
+    def self.call_llm(messages)
+      # In a real implementation, this would call OpenAI, Claude, etc.
+      # For demo purposes, we'll just echo the last user message
+      last_user_message = messages.reverse.find { |msg| msg[:role] == :user }
+      return "I heard you say: #{last_user_message[:content]}" if last_user_message
+
+      "Hello! How can I help you today?"
+    end
+  end
+
+  class ChatNode < FlowNodes::Node
+    # Initialize messages array + prompt for user input.
+    def prep(shared)
+      unless shared.key?(:messages)
+        shared[:messages] = []
+        shared[:chat_session_id] = SecureRandom.hex(8)
+        shared[:start_time] = Time.now
+        puts "🤖 Welcome to the chat! Type 'exit' to end the conversation."
+        puts "📊 Session ID: #{shared[:chat_session_id]}"
+      end
+
+      print "\nYou: "
+      user_input = $stdin.gets
+      return nil unless user_input # EOF (Ctrl-D)
+
+      user_input = user_input.chomp
+      return nil if user_input.strip.downcase == "exit"
+
+      # push user message
+      shared[:messages] << { role: :user, content: user_input }
+      shared[:turn_count] = (shared[:turn_count] || 0) + 1
+      
+      puts "🔄 Processing turn #{shared[:turn_count]}..."
+      shared[:messages]
+    end
+
+    # Call the LLM with full history.
+    def exec(messages)
+      return nil unless messages
+
+      puts "🧠 Calling LLM with #{messages.length} messages..."
+      Utils.call_llm(messages)
+    end
+
+    # Print assistant reply, store it, and loop.
+    def post(shared, prep_res, exec_res)
+      if prep_res.nil? || exec_res.nil?
+        duration = Time.now - shared[:start_time]
+        puts "\n👋 Goodbye!"
+        puts "📊 Chat session stats:"
+        puts "   - Session ID: #{shared[:chat_session_id]}"
+        puts "   - Total turns: #{shared[:turn_count] || 0}"
+        puts "   - Duration: #{duration.round(2)}s"
+        puts "   - Messages: #{shared[:messages]&.length || 0}"
+        return nil
+      end
+
+      puts "\n🤖 Assistant: #{exec_res}"
+      shared[:messages] << { role: :assistant, content: exec_res }
+      :continue
+    end
+
+    # Optional: graceful fallback on final retry failure.
+    def exec_fallback(_prep_res, exc)
+      puts "⚠️  LLM service unavailable: #{exc.class}: #{exc.message}"
+      puts "🔄 Retrying in a moment..."
+      :continue
+    end
+  end
+end
+
+# Demo script
+if $PROGRAM_NAME == __FILE__
+  shared = {}
+  chat_node = ChatDemo::ChatNode.new
+
+  # Create self-loop: when exec returns "continue", go back to same node
+  chat_node - :continue >> chat_node
+
+  # Create flow and run
+  flow = FlowNodes::Flow.new(start: chat_node)
+  flow.run(shared)
+end