flow_nodes 0.1.0

data/examples/llm_document_analyzer.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require_relative "../lib/flow_nodes"
+require "json"
+require "securerandom"
+
+# Simple LLM Document Analysis Pipeline
+# This demonstrates the core patterns for LLM integration with FlowNodes:
+# 1. Document ingestion
+# 2. LLM analysis with proper error handling
+# 3. Result formatting and delivery
+# 4. Symbol-based flow control
+
+module LLMDocumentAnalyzer
+  # Mock LLM service
+  class LLMService
+    def self.analyze_document(content, analysis_type = "summary")
+      case analysis_type
+      when "summary"
+        { 
+          summary: content.split('.').first(2).join('.') + '.',
+          word_count: content.split.length,
+          key_themes: ["productivity", "analysis", "automation"]
+        }
+      when "sentiment"
+        {
+          sentiment: content.include?("good") ? "positive" : "neutral",
+          confidence: 0.85,
+          emotional_tone: "professional"
+        }
+      when "extract_entities"
+        {
+          people: content.scan(/\b[A-Z][a-z]+ [A-Z][a-z]+\b/),
+          organizations: content.scan(/\b[A-Z][a-z]+ Inc\.|Corp\.|LLC\b/),
+          dates: content.scan(/\d{4}-\d{2}-\d{2}/)
+        }
+      else
+        { error: "Unknown analysis type: #{analysis_type}" }
+      end
+    end
+  end
+
+  class DocumentIngestionNode < FlowNodes::Node
+    def prep(state)
+      puts "📄 Starting document ingestion..."
+      state[:start_time] = Time.now
+      nil
+    end
+
+    def exec(params)
+      puts "📊 Loading document: #{params[:document_path] || 'sample.txt'}"
+      
+      # Mock document content
+      document = {
+        id: SecureRandom.hex(4),
+        content: "This is a sample document for analysis. It contains good information about productivity and automation tools. The document discusses various approaches to streamline workflows and improve efficiency.",
+        metadata: {
+          title: "Sample Document",
+          author: "John Smith",
+          created_at: "2024-01-15",
+          word_count: 31
+        }
+      }
+      
+      puts "✅ Document loaded successfully"
+      
+      # Store document for next node
+      @params.merge!(document: document)
+      
+      :document_loaded
+    end
+
+    def post(state, params, result)
+      puts "📈 Document ingestion completed"
+    end
+  end
+
+  class LLMAnalysisNode < FlowNodes::Node
+    def initialize(analysis_type: "summary")
+      super(max_retries: 3, wait: 1)
+      @analysis_type = analysis_type
+    end
+
+    def prep(state)
+      puts "🤖 Starting LLM analysis: #{@analysis_type}"
+      state[:llm_start] = Time.now
+      nil
+    end
+
+    def exec(params)
+      document = params[:document]
+      
+      unless document
+        puts "❌ No document found in params"
+        return :missing_document
+      end
+      
+      puts "🧠 Analyzing document: #{document[:id]}"
+      
+      # Call LLM service
+      analysis_result = LLMService.analyze_document(document[:content], @analysis_type)
+      
+      puts "✅ LLM analysis completed"
+      
+      # Store analysis result
+      @params.merge!(analysis: analysis_result)
+      
+      :analysis_completed
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:llm_start]
+      puts "📈 LLM analysis completed in #{duration.round(3)}s"
+    end
+
+    def exec_fallback(params, exception)
+      puts "⚠️  LLM analysis failed: #{exception.message}"
+      
+      # Fallback analysis
+      @params.merge!(analysis: { error: "LLM service unavailable", fallback: true })
+      
+      :analysis_failed
+    end
+  end
+
+  class ResultFormattingNode < FlowNodes::Node
+    def initialize(format: "json")
+      super()
+      @format = format
+    end
+
+    def prep(state)
+      puts "📝 Formatting results as #{@format}"
+      nil
+    end
+
+    def exec(params)
+      document = params[:document]
+      analysis = params[:analysis]
+      
+      formatted_result = case @format
+      when "json"
+        JSON.pretty_generate({
+          document: document,
+          analysis: analysis,
+          processed_at: Time.now
+        })
+      when "summary"
+        """
+Document Analysis Results
+========================
+
+Document: #{document[:metadata][:title]}
+Author: #{document[:metadata][:author]}
+Analysis Type: summary
+
+Results:
+#{analysis.map { |k, v| "#{k}: #{v}" }.join("\n")}
+
+Processed at: #{Time.now}
+"""
+      else
+        "Analysis completed for document #{document[:id]}"
+      end
+      
+      puts "✅ Results formatted successfully"
+      
+      @params.merge!(formatted_result: formatted_result)
+      
+      :results_formatted
+    end
+
+    def post(state, params, result)
+      puts "📈 Results formatting completed"
+    end
+  end
+
+  class OutputDeliveryNode < FlowNodes::Node
+    def prep(state)
+      puts "📤 Preparing output delivery"
+      nil
+    end
+
+    def exec(params)
+      puts "🚀 Delivering results..."
+      
+      # Display results
+      puts "\n" + "="*50
+      puts "📋 DOCUMENT ANALYSIS RESULTS"
+      puts "="*50
+      puts params[:formatted_result]
+      puts "="*50
+      
+      puts "\n✅ Analysis pipeline completed successfully!"
+      
+      nil # End flow
+    end
+
+    def post(state, params, result)
+      if state[:start_time]
+        total_duration = Time.now - state[:start_time]
+        puts "📈 Total pipeline duration: #{total_duration.round(3)}s"
+      end
+    end
+  end
+
+  class ErrorHandlerNode < FlowNodes::Node
+    def prep(state)
+      puts "🚨 Handling analysis error"
+      nil
+    end
+
+    def exec(params)
+      puts "❌ LLM analysis failed, providing fallback response"
+      
+      # Simple fallback
+      @params.merge!(
+        formatted_result: "Document analysis failed. Please try again later."
+      )
+      
+      :error_handled
+    end
+
+    def post(state, params, result)
+      puts "🔧 Error handling completed"
+    end
+  end
+end
+
+# Demo showing LLM document analysis
+if $PROGRAM_NAME == __FILE__
+  puts "🤖 LLM DOCUMENT ANALYSIS PIPELINE"
+  puts "=" * 45
+
+  # Create nodes
+  ingestion = LLMDocumentAnalyzer::DocumentIngestionNode.new
+  analysis = LLMDocumentAnalyzer::LLMAnalysisNode.new(analysis_type: "summary")
+  formatting = LLMDocumentAnalyzer::ResultFormattingNode.new(format: "summary")
+  delivery = LLMDocumentAnalyzer::OutputDeliveryNode.new
+  error_handler = LLMDocumentAnalyzer::ErrorHandlerNode.new
+
+  # Connect with symbol-based routing
+  ingestion - :document_loaded >> analysis
+  analysis - :analysis_completed >> formatting
+  analysis - :analysis_failed >> error_handler
+  formatting - :results_formatted >> delivery
+  error_handler - :error_handled >> delivery
+
+  # Create flow
+  flow = FlowNodes::Flow.new(start: ingestion)
+  
+  # Test successful analysis
+  puts "\n📋 SCENARIO 1: Successful Document Analysis"
+  puts "-" * 40
+  state = { pipeline_id: SecureRandom.hex(4) }
+  flow.set_params(document_path: "sample_document.txt")
+  flow.run(state)
+
+  # Test with different analysis type
+  puts "\n📋 SCENARIO 2: Sentiment Analysis"
+  puts "-" * 40
+  sentiment_analysis = LLMDocumentAnalyzer::LLMAnalysisNode.new(analysis_type: "sentiment")
+  json_formatting = LLMDocumentAnalyzer::ResultFormattingNode.new(format: "json")
+
+  # Create new flow for sentiment analysis
+  ingestion - :document_loaded >> sentiment_analysis
+  sentiment_analysis - :analysis_completed >> json_formatting
+  json_formatting - :results_formatted >> delivery
+
+  flow2 = FlowNodes::Flow.new(start: ingestion)
+  state2 = { pipeline_id: SecureRandom.hex(4) }
+  flow2.set_params(document_path: "sentiment_test.txt")
+  flow2.run(state2)
+
+  puts "\n🎯 All document analysis scenarios completed!"
+end

data/examples/simple_llm_example.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "../lib/flow_nodes"
+
+# Simple LLM Integration Example
+# This demonstrates the core patterns for LLM workflows with FlowNodes
+
+module SimpleLLMExample
+  # Mock LLM service
+  class LLMService
+    def self.process(text, operation)
+      case operation
+      when "summarize"
+        "Summary: #{text.split('.').first}."
+      when "classify"
+        text.downcase.include?("error") ? "error_report" : "general_content"
+      when "extract_keywords"
+        text.scan(/\b\w{4,}\b/).uniq.first(3).join(", ")
+      else
+        "Processed: #{text}"
+      end
+    end
+  end
+
+  class TextInputNode < FlowNodes::Node
+    def exec(params)
+      puts "📄 Processing text input..."
+      
+      # Simulate getting text from params
+      text = params[:text] || "This is a sample document about productivity tools. Error handling is important."
+      
+      puts "📝 Text received: #{text[0..50]}..."
+      
+      # Return text for next node
+      text
+    end
+  end
+
+  class LLMProcessorNode < FlowNodes::Node
+    def initialize(operation: "summarize")
+      super()
+      @operation = operation
+    end
+
+    def exec(text)
+      puts "🤖 Processing with LLM operation: #{@operation}"
+      
+      # Call LLM service
+      result = LLMService.process(text, @operation)
+      
+      puts "✅ LLM processing completed"
+      
+      # Return result
+      result
+    end
+  end
+
+  class OutputNode < FlowNodes::Node
+    def exec(result)
+      puts "📤 Delivering result:"
+      puts "Result: #{result}"
+      
+      nil # End flow
+    end
+  end
+
+  # Conditional node that routes based on classification
+  class ClassificationRouterNode < FlowNodes::Node
+    def exec(text)
+      puts "🔍 Classifying content..."
+      
+      classification = LLMService.process(text, "classify")
+      
+      puts "📋 Classification: #{classification}"
+      
+      # Return symbol for routing
+      classification.to_sym
+    end
+  end
+
+  class ErrorHandlerNode < FlowNodes::Node
+    def exec(text)
+      puts "🚨 Handling error content..."
+      puts "Error analysis: #{text[0..100]}"
+      
+      nil # End flow
+    end
+  end
+
+  class GeneralProcessorNode < FlowNodes::Node
+    def exec(text)
+      puts "📊 Processing general content..."
+      
+      keywords = LLMService.process(text, "extract_keywords")
+      summary = LLMService.process(text, "summarize")
+      
+      puts "Keywords: #{keywords}"
+      puts "Summary: #{summary}"
+      
+      nil # End flow
+    end
+  end
+end
+
+# Demo showing different LLM workflow patterns
+if $PROGRAM_NAME == __FILE__
+  puts "🤖 SIMPLE LLM WORKFLOW EXAMPLES"
+  puts "=" * 40
+
+  # Example 1: Basic LLM Pipeline
+  puts "\n📋 EXAMPLE 1: Basic LLM Processing"
+  puts "-" * 30
+  
+  input_node = SimpleLLMExample::TextInputNode.new
+  llm_processor = SimpleLLMExample::LLMProcessorNode.new(operation: "summarize")
+  output_node = SimpleLLMExample::OutputNode.new
+
+  # Connect nodes
+  input_node >> llm_processor >> output_node
+
+  # Create and run flow
+  flow = FlowNodes::Flow.new(start: input_node)
+  flow.set_params(text: "This is a comprehensive document about artificial intelligence and machine learning applications. The technology shows great promise for automation.")
+  flow.run(nil)
+
+  # Example 2: Conditional LLM Routing
+  puts "\n📋 EXAMPLE 2: Conditional LLM Routing"
+  puts "-" * 30
+  
+  input_node = SimpleLLMExample::TextInputNode.new
+  classifier = SimpleLLMExample::ClassificationRouterNode.new
+  error_handler = SimpleLLMExample::ErrorHandlerNode.new
+  general_processor = SimpleLLMExample::GeneralProcessorNode.new
+
+  # Connect with conditional routing
+  input_node >> classifier
+  classifier - :error_report >> error_handler
+  classifier - :general_content >> general_processor
+
+  # Test with error content
+  flow = FlowNodes::Flow.new(start: input_node)
+  flow.set_params(text: "System error occurred during processing. Database connection failed.")
+  flow.run(nil)
+
+  # Test with general content
+  flow.set_params(text: "Today's productivity tips focus on time management and workflow optimization.")
+  flow.run(nil)
+
+  # Example 3: Multi-step LLM Processing
+  puts "\n📋 EXAMPLE 3: Multi-step LLM Processing"
+  puts "-" * 30
+  
+  input_node = SimpleLLMExample::TextInputNode.new
+  summarizer = SimpleLLMExample::LLMProcessorNode.new(operation: "summarize")
+  keyword_extractor = SimpleLLMExample::LLMProcessorNode.new(operation: "extract_keywords")
+  output_node = SimpleLLMExample::OutputNode.new
+
+  # Chain multiple LLM operations
+  input_node >> summarizer >> keyword_extractor >> output_node
+
+  flow = FlowNodes::Flow.new(start: input_node)
+  flow.set_params(text: "Artificial intelligence and machine learning are transforming modern business operations. Companies are investing heavily in automation technologies to improve efficiency and reduce costs.")
+  flow.run(nil)
+
+  puts "\n🎯 All LLM workflow examples completed!"
+end

data/examples/workflow.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "../lib/flow_nodes"
+require "securerandom"
+
+module WorkflowDemo
+  class DataValidationNode < FlowNodes::Node
+    def prep(state)
+      puts "🔍 Starting validation process..."
+      state[:validation_start] = Time.now
+      nil # Use node's own params
+    end
+
+    def exec(data)
+      puts "📝 Validating data: #{data.inspect}"
+      return :invalid if data.nil? || data.empty?
+      return :invalid unless data.is_a?(Hash)
+      return :invalid unless data.key?(:email) && data.key?(:name)
+
+      :valid
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:validation_start]
+      puts "✅ Validation completed in #{duration.round(3)}s with result: #{result}"
+      state[:validation_result] = result
+    end
+  end
+
+  class ProcessDataNode < FlowNodes::Node
+    def prep(state)
+      puts "⚙️  Preparing data processing..."
+      state[:processing_start] = Time.now
+      # Transform params - add processing metadata
+      @params.merge({
+        processing_id: SecureRandom.hex(8),
+        processed_at: Time.now
+      })
+    end
+
+    def exec(data)
+      puts "⚡ Processing data for #{data[:name]} (#{data[:email]})"
+      puts "📊 Processing ID: #{data[:processing_id]}"
+      
+      # Simulate processing work
+      sleep(0.1)
+      
+      data[:processed] = true
+      data[:processed_at] = Time.now
+      :success
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:processing_start]
+      puts "✅ Processing completed in #{duration.round(3)}s"
+      state[:processed_count] = (state[:processed_count] || 0) + 1
+    end
+  end
+
+  class SendEmailNode < FlowNodes::Node
+    def prep(state)
+      puts "📧 Preparing email service..."
+      state[:email_attempts] = (state[:email_attempts] || 0) + 1
+      nil
+    end
+
+    def exec(data)
+      puts "📤 Sending welcome email to #{data[:email]}"
+      puts "📊 Processing ID: #{data[:processing_id]}"
+      
+      # Simulate email sending
+      sleep(0.1)
+      
+      :email_sent
+    end
+
+    def post(state, params, result)
+      puts "✅ Email sent successfully"
+      state[:emails_sent] = (state[:emails_sent] || 0) + 1
+      state[:last_email_sent] = Time.now
+    end
+  end
+
+  class ErrorHandlerNode < FlowNodes::Node
+    def prep(state)
+      puts "🚨 Error handling activated..."
+      state[:error_count] = (state[:error_count] || 0) + 1
+      nil
+    end
+
+    def exec(data)
+      puts "❌ Error: Invalid data received - #{data}"
+      puts "📊 Total errors handled: #{@params[:error_count] || 0}"
+      :error_handled
+    end
+
+    def post(state, params, result)
+      puts "🔧 Error handling completed"
+      state[:last_error_handled] = Time.now
+    end
+  end
+
+  class CompletionNode < FlowNodes::Node
+    def prep(state)
+      puts "🎯 Finalizing workflow..."
+      state[:completion_start] = Time.now
+      nil
+    end
+
+    def exec(data)
+      puts "🎉 Workflow completed successfully for #{data[:name]}"
+      puts "📊 Processing ID: #{data[:processing_id]}"
+      puts "📈 Final data: #{data}"
+      nil # End the flow
+    end
+
+    def post(state, params, result)
+      duration = Time.now - state[:completion_start]
+      puts "✅ Workflow finalized in #{duration.round(3)}s"
+      puts "📊 Final state: #{state}"
+    end
+  end
+end
+
+# Demo script
+if $PROGRAM_NAME == __FILE__
+  # Create nodes
+  validator = WorkflowDemo::DataValidationNode.new
+  processor = WorkflowDemo::ProcessDataNode.new
+  emailer = WorkflowDemo::SendEmailNode.new
+  error_handler = WorkflowDemo::ErrorHandlerNode.new
+  completion = WorkflowDemo::CompletionNode.new
+
+  # Connect the workflow using symbols
+  validator - :valid >> processor
+  validator - :invalid >> error_handler
+  processor - :success >> emailer  
+  emailer - :email_sent >> completion
+
+  # Create flow
+  flow = FlowNodes::Flow.new(start: validator)
+
+  # Test with valid data
+  puts "=== Testing with valid data ==="
+  state = { workflow_id: SecureRandom.hex(4) }
+  flow.set_params({ email: "user@example.com", name: "John Doe" })
+  flow.run(state)
+
+  puts "\n=== Testing with invalid data ==="
+  state = { workflow_id: SecureRandom.hex(4) }
+  flow.set_params({ invalid: "data" })
+  flow.run(state)
+
+  puts "\n=== Testing with nil data ==="
+  state = { workflow_id: SecureRandom.hex(4) }
+  flow.set_params(nil)
+  flow.run(state)
+end

data/lib/flow_nodes/async_batch_flow.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # An async flow that processes a batch of items sequentially.
+  class AsyncBatchFlow < AsyncFlow
+    protected
+
+    def _run_async(s)
+      batch_params = prep_async(s) || []
+      batch_params.each do |item_params|
+        _orch_async(s, params: @params.merge(item_params))
+      end
+      post_async(s, batch_params, nil)
+    end
+  end
+end

data/lib/flow_nodes/async_batch_node.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # An async node that processes a batch of items sequentially.
+  class AsyncBatchNode < AsyncNode
+    protected
+
+    def _exec_async(items)
+      return [] if items.nil?
+
+      items_array = items.is_a?(Array) ? items : [items]
+      items_array.map { |item| super(item) }
+    end
+  end
+end

data/lib/flow_nodes/async_flow.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # A flow that can orchestrate both synchronous and asynchronous nodes.
+  class AsyncFlow < Flow
+    def run(s) = run_async(s)
+
+    def run_async(s)
+      _run_async(s)
+    end
+
+    def _run(_s)
+      raise "Use run_async for AsyncFlow."
+    end
+
+    protected
+
+    def prep_async(_s) = nil
+    def post_async(_s, _p, _e) = nil
+
+    def _run_async(s)
+      prepared_params = prep_async(s)
+      result = _orch_async(s, params: prepared_params || @params)
+      post_async(s, prepared_params, result)
+      result
+    end
+
+    # @note Asynchronous operations use Ruby threads and are subject to the GVL.
+    # This is best suited for I/O-bound tasks, not CPU-bound parallel processing.
+    def _orch_async(state, params: nil)
+      raise "Flow has no start node" unless @start_node
+
+      current_node = @start_node.dup
+      flow_params = params ? params.dup : @params.dup
+      last_result = nil
+
+      while current_node
+        current_node.set_params(flow_params)
+        last_result = if current_node.is_a?(AsyncNode)
+                        current_node.send(:_run_async, state)
+                      else
+                        current_node._run(state)
+                      end
+        current_node = get_next_node(current_node, last_result)&.dup
+      end
+      last_result
+    end
+  end
+end