langgraph_rb 0.1.0 → 0.1.1

data/examples/observer_example.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/langgraph_rb'
+require 'logger'
+
+# Custom observer for metrics collection
+class MetricsObserver < LangGraphRB::Observers::BaseObserver
+  def initialize(metrics_client)
+    @metrics = metrics_client
+  end
+
+  def on_node_end(event)
+    @metrics.histogram('node.duration', event.duration * 1000, {
+      node_name: event.node_name.to_s,
+      node_type: event.node_class&.name
+    })
+  end
+
+  def on_node_error(event)
+    @metrics.increment('node.error', {
+      node_name: event.node_name.to_s,
+      error_type: event.error&.class&.name
+    })
+  end
+end
+
+# Database observer for audit trails
+class DatabaseObserver < LangGraphRB::Observers::BaseObserver
+  def initialize(db_connection)
+    @db = db_connection
+  end
+
+  def on_graph_start(event)
+    @db.execute(
+      "INSERT INTO graph_executions (thread_id, graph_class, started_at) VALUES (?, ?, ?)",
+      event.thread_id, event.graph.class.name, event.timestamp
+    )
+  end
+
+  def on_node_end(event)
+    @db.execute(
+      "INSERT INTO node_executions (thread_id, step_number, node_name, duration_ms, completed_at) VALUES (?, ?, ?, ?, ?)",
+      event.thread_id, event.step_number, event.node_name.to_s, (event.duration * 1000).round(2), event.timestamp
+    )
+  end
+end
+
+class MyMetricsClient
+  def histogram(name, value, tags)
+    puts "Histogram: #{name}, #{value}, #{tags}"
+  end
+
+  def increment(name, tags)
+    puts "Increment: #{name}, #{tags}"
+  end
+end
+
+class MyDBConnection
+  def execute(query, *args)
+    puts "Executing: #{query}, #{args}"
+  end
+end
+
+def observer_example
+  puts "=== Observer Example ==="
+  
+  # Create a simple graph for demonstration
+  initial_state = LangGraphRB::State.new(
+    { message: "", messages: [], response: "" }
+  )
+
+  # Create the graph using DSL
+  graph = LangGraphRB::Graph.new(state_class: LangGraphRB::State) do
+    # Simple node that processes messages
+    node :process_message do |state|
+      puts "Processing: #{state[:message]}"
+      {
+        messages: state[:messages] + [state[:message]],
+        response: "Processed: #{state[:message]}"
+      }
+    end
+
+    # Set up the flow
+    set_entry_point :process_message
+    set_finish_point :process_message
+  end
+
+  # Compile the graph
+  graph.compile!
+
+  # Basic logging observability
+  logger_observer = LangGraphRB::Observers::LoggerObserver.new(
+    logger: Logger.new('graph_execution.log'),
+    level: :info
+  )
+
+  puts "\n--- Running with basic logging observer ---"
+  graph.invoke(
+    { message: "Hello World", messages: [], response: "" },
+    observers: [logger_observer]
+  )
+
+  my_metrics_client = MyMetricsClient.new
+  my_db_connection = MyDBConnection.new
+
+  # Use multiple observers
+  puts "\n--- Running with multiple observers ---"
+  graph.invoke(
+    { message: "Testing multiple observers", messages: [], response: "" },
+    observers: [
+      logger_observer,
+      MetricsObserver.new(my_metrics_client),
+      DatabaseObserver.new(my_db_connection)
+    ]
+  )
+  
+  puts "\nObserver example completed! Check 'graph_execution.log' for logged events."
+end
+
+# Run the example
+observer_example if __FILE__ == $0

data/examples/reducers_example.rb

@@ -0,0 +1,337 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/langgraph_rb'
+
+# Custom state class for workflow example
+class UserSetupState < LangGraphRB::State
+  def initialize(schema = {}, reducers = nil)
+    # If reducers are not provided, use our default reducers
+    reducers ||= { user_info: LangGraphRB::State.merge_hash }
+    super(schema, reducers)
+  end
+end
+
+# Example 1: WITHOUT Reducers - Simple Replacement Behavior
+def without_reducers_example
+  puts "\n" + "=" * 60
+  puts "🔴 EXAMPLE 1: WITHOUT REDUCERS (Simple Replacement)"
+  puts "=" * 60
+  
+  # Create state without any reducers - everything is simple replacement
+  state = LangGraphRB::State.new({ 
+    counter: 0, 
+    messages: [], 
+    user_data: { name: "Alice" }
+  })
+  
+  puts "Initial state:"
+  puts "  Counter: #{state[:counter]}"
+  puts "  Messages: #{state[:messages]}"
+  puts "  User data: #{state[:user_data]}"
+  
+  # First update - this will REPLACE the values completely
+  puts "\n📝 First update: { counter: 5, messages: ['Hello'], user_data: { age: 25 } }"
+  state = state.merge_delta({ 
+    counter: 5, 
+    messages: ['Hello'], 
+    user_data: { age: 25 }
+  })
+  
+  puts "After first update:"
+  puts "  Counter: #{state[:counter]} ← REPLACED with 5"
+  puts "  Messages: #{state[:messages]} ← REPLACED with ['Hello']"
+  puts "  User data: #{state[:user_data]} ← REPLACED with { age: 25 } (name is LOST!)"
+  
+  # Second update - again, simple replacement
+  puts "\n📝 Second update: { counter: 3, messages: ['World'], user_data: { city: 'NYC' } }"
+  state = state.merge_delta({ 
+    counter: 3, 
+    messages: ['World'], 
+    user_data: { city: 'NYC' }
+  })
+  
+  puts "After second update:"
+  puts "  Counter: #{state[:counter]} ← REPLACED with 3 (lost the 5!)"
+  puts "  Messages: #{state[:messages]} ← REPLACED with ['World'] (lost 'Hello'!)"
+  puts "  User data: #{state[:user_data]} ← REPLACED with { city: 'NYC' } (lost age!)"
+  
+  puts "\n❌ PROBLEM: Without reducers, we lose previous data on every update!"
+end
+
+# Example 2: WITH Reducers - Intelligent Merging
+def with_reducers_example
+  puts "\n" + "=" * 60
+  puts "🟢 EXAMPLE 2: WITH REDUCERS (Intelligent Merging)"
+  puts "=" * 60
+  
+  # Create state WITH reducers that define how to combine values
+  state = LangGraphRB::State.new(
+    { 
+      counter: 0, 
+      messages: [], 
+      user_data: { name: "Alice" }
+    },
+    { 
+      counter: ->(old, new) { (old || 0) + new },           # ADD numbers
+      messages: LangGraphRB::State.add_messages,             # APPEND to array
+      user_data: LangGraphRB::State.merge_hash               # MERGE hashes
+    }
+  )
+  
+  puts "Initial state:"
+  puts "  Counter: #{state[:counter]}"
+  puts "  Messages: #{state[:messages]}"
+  puts "  User data: #{state[:user_data]}"
+  
+  # First update - reducers will intelligently combine values
+  puts "\n📝 First update: { counter: 5, messages: ['Hello'], user_data: { age: 25 } }"
+  state = state.merge_delta({ 
+    counter: 5, 
+    messages: ['Hello'], 
+    user_data: { age: 25 }
+  })
+  
+  puts "After first update:"
+  puts "  Counter: #{state[:counter]} ← ADDED: 0 + 5 = 5"
+  puts "  Messages: #{state[:messages]} ← APPENDED: [] + ['Hello'] = ['Hello']"
+  puts "  User data: #{state[:user_data]} ← MERGED: {name: 'Alice'} + {age: 25}"
+  
+  # Second update - reducers continue to combine intelligently
+  puts "\n📝 Second update: { counter: 3, messages: ['World'], user_data: { city: 'NYC' } }"
+  state = state.merge_delta({ 
+    counter: 3, 
+    messages: ['World'], 
+    user_data: { city: 'NYC' }
+  })
+  
+  puts "After second update:"
+  puts "  Counter: #{state[:counter]} ← ADDED: 5 + 3 = 8"
+  puts "  Messages: #{state[:messages]} ← APPENDED: ['Hello'] + ['World']"
+  puts "  User data: #{state[:user_data]} ← MERGED: keeps all previous data!"
+  
+  puts "\n✅ SUCCESS: With reducers, we intelligently combine data instead of losing it!"
+end
+
+# Example 3: Built-in Reducers Demonstration
+def builtin_reducers_example
+  puts "\n" + "=" * 60
+  puts "🛠️  EXAMPLE 3: BUILT-IN REDUCERS"
+  puts "=" * 60
+  
+  # Demonstrate each built-in reducer
+  puts "📌 1. add_messages - For building conversation history"
+  messages_state = LangGraphRB::State.new(
+    { messages: [] },
+    { messages: LangGraphRB::State.add_messages }
+  )
+  
+  messages_state = messages_state.merge_delta({ messages: { role: 'user', content: 'Hi!' } })
+  messages_state = messages_state.merge_delta({ messages: [{ role: 'assistant', content: 'Hello!' }] })
+  messages_state = messages_state.merge_delta({ messages: { role: 'user', content: 'How are you?' } })
+  
+  puts "Messages history: #{messages_state[:messages]}"
+  
+  puts "\n📌 2. append_string - For building text content"
+  text_state = LangGraphRB::State.new(
+    { story: "" },
+    { story: LangGraphRB::State.append_string }
+  )
+  
+  text_state = text_state.merge_delta({ story: "Once upon a time, " })
+  text_state = text_state.merge_delta({ story: "there was a brave knight " })
+  text_state = text_state.merge_delta({ story: "who saved the kingdom." })
+  
+  puts "Story: \"#{text_state[:story]}\""
+  
+  puts "\n📌 3. merge_hash - For building complex objects"
+  profile_state = LangGraphRB::State.new(
+    { profile: {} },
+    { profile: LangGraphRB::State.merge_hash }
+  )
+  
+  profile_state = profile_state.merge_delta({ profile: { name: "Bob" } })
+  profile_state = profile_state.merge_delta({ profile: { age: 30, city: "Boston" } })
+  profile_state = profile_state.merge_delta({ profile: { job: "Developer", age: 31 } }) # age updated
+  
+  puts "Profile: #{profile_state[:profile]}"
+end
+
+# Example 4: Custom Reducers
+def custom_reducers_example
+  puts "\n" + "=" * 60
+  puts "⚙️  EXAMPLE 4: CUSTOM REDUCERS"
+  puts "=" * 60
+  
+  # Custom reducer: Keep maximum value
+  max_reducer = ->(old, new) { [old || 0, new || 0].max }
+  
+  # Custom reducer: Keep unique items in array
+  unique_array_reducer = ->(old, new) do
+    old_array = old || []
+    new_items = new.is_a?(Array) ? new : [new]
+    (old_array + new_items).uniq
+  end
+  
+  # Custom reducer: Track changes with timestamps
+  history_reducer = ->(old, new) do
+    old_history = old || []
+    timestamp = Time.now.strftime("%H:%M:%S")
+    old_history + [{ value: new, timestamp: timestamp }]
+  end
+  
+  state = LangGraphRB::State.new(
+    { 
+      max_score: 0, 
+      unique_tags: [], 
+      value_history: []
+    },
+    {
+      max_score: max_reducer,
+      unique_tags: unique_array_reducer,
+      value_history: history_reducer
+    }
+  )
+  
+  puts "📊 Testing custom reducers..."
+  
+  # Test updates
+  state = state.merge_delta({ max_score: 85, unique_tags: ['ruby', 'programming'], value_history: 'first' })
+  puts "After update 1:"
+  puts "  Max score: #{state[:max_score]}"
+  puts "  Unique tags: #{state[:unique_tags]}"
+  puts "  History: #{state[:value_history]}"
+  
+  sleep(1) # Small delay to show different timestamps
+  
+  state = state.merge_delta({ max_score: 72, unique_tags: ['ruby', 'web', 'api'], value_history: 'second' })
+  puts "\nAfter update 2:"
+  puts "  Max score: #{state[:max_score]} ← Kept the higher value (85)"
+  puts "  Unique tags: #{state[:unique_tags]} ← Added new unique tags"
+  puts "  History: #{state[:value_history]} ← Tracked all changes with timestamps"
+  
+  sleep(1)
+  
+  state = state.merge_delta({ max_score: 95, unique_tags: ['programming'], value_history: 'third' })
+  puts "\nAfter update 3:"
+  puts "  Max score: #{state[:max_score]} ← New maximum!"
+  puts "  Unique tags: #{state[:unique_tags]} ← No duplicates added"
+  puts "  History: #{state[:value_history]} ← Complete change history"
+end
+
+# Example 5: Real-world Graph Workflow Comparison
+def workflow_comparison_example
+  puts "\n" + "=" * 60
+  puts "🚀 EXAMPLE 5: REAL-WORLD WORKFLOW COMPARISON"
+  puts "=" * 60
+  
+  puts "🔴 WITHOUT Reducers - Data Loss Problem:"
+  
+  # Workflow without reducers
+  graph_without = LangGraphRB::Graph.new do
+    node :collect_user_info do |state|
+      { user_info: { name: state[:name] } }
+    end
+    
+    node :collect_preferences do |state|
+      { user_info: { theme: state[:theme] } } # This OVERWRITES name!
+    end
+    
+    node :finalize do |state|
+      { result: "User setup complete: #{state[:user_info]}" }
+    end
+    
+    set_entry_point :collect_user_info
+    edge :collect_user_info, :collect_preferences
+    edge :collect_preferences, :finalize
+    set_finish_point :finalize
+  end
+  
+  graph_without.compile!
+  result_without = graph_without.invoke({ name: "Alice", theme: "dark" })
+  puts "❌ Result: #{result_without[:result]} ← Lost the name!"
+  
+  puts "\n🟢 WITH Reducers - Data Preservation:"
+  
+  # Workflow with reducers
+  graph_with = LangGraphRB::Graph.new(state_class: UserSetupState) do
+    node :collect_user_info do |state|
+      { user_info: { name: state[:name] } }
+    end
+    
+    node :collect_preferences do |state|
+      { user_info: { theme: state[:theme] } } # This MERGES with name!
+    end
+    
+    node :finalize do |state|
+      { result: "User setup complete: #{state[:user_info]}" }
+    end
+    
+    set_entry_point :collect_user_info
+    edge :collect_user_info, :collect_preferences
+    edge :collect_preferences, :finalize
+    set_finish_point :finalize
+  end
+  
+  graph_with.compile!
+  result_with = graph_with.invoke({ name: "Alice", theme: "dark" })
+  puts "✅ Result: #{result_with[:result]} ← Preserved all data!"
+end
+
+# Example 6: Performance and Memory Considerations
+def performance_example
+  puts "\n" + "=" * 60
+  puts "⚡ EXAMPLE 6: PERFORMANCE CONSIDERATIONS"
+  puts "=" * 60
+  
+  puts "🔍 Memory efficiency with reducers:"
+  
+  # Show how reducers create new state objects (immutable)
+  original_state = LangGraphRB::State.new(
+    { data: [1, 2, 3] },
+    { data: LangGraphRB::State.add_messages }
+  )
+  
+  puts "Original state object_id: #{original_state.object_id}"
+  puts "Original data object_id: #{original_state[:data].object_id}"
+  
+  new_state = original_state.merge_delta({ data: [4, 5] })
+  
+  puts "New state object_id: #{new_state.object_id} ← Different object (immutable)"
+  puts "New data object_id: #{new_state[:data].object_id} ← New array object"
+  puts "Original data unchanged: #{original_state[:data]} ← Still [1, 2, 3]"
+  puts "New data: #{new_state[:data]} ← Combined result [1, 2, 3, 4, 5]"
+  
+  puts "\n💡 Key Benefits:"
+  puts "  • Immutable updates (thread-safe)"
+  puts "  • Predictable state changes"
+  puts "  • Easy to debug and test"
+  puts "  • Prevents accidental data loss"
+end
+
+# Run all examples
+def run_all_examples
+  puts "🧪 LangGraphRB State Reducers - Complete Tutorial"
+  puts "=" * 80
+  
+  without_reducers_example
+  with_reducers_example
+  builtin_reducers_example
+  custom_reducers_example
+  workflow_comparison_example
+  performance_example
+  
+  puts "\n" + "=" * 80
+  puts "🎯 KEY TAKEAWAYS:"
+  puts "1. Without reducers: Simple replacement (data loss risk)"
+  puts "2. With reducers: Intelligent merging (data preservation)"
+  puts "3. Built-in reducers: add_messages, append_string, merge_hash"
+  puts "4. Custom reducers: Define your own combination logic"
+  puts "5. Graph workflows: Reducers prevent data loss between nodes"
+  puts "6. Immutable updates: Thread-safe and predictable"
+  puts "=" * 80
+end
+
+# Run the complete tutorial
+if __FILE__ == $0
+  run_all_examples
+end

data/lib/langgraph_rb/graph.rb

@@ -96,7 +96,7 @@ module LangGraphRB
     end
 
     # Execute the graph synchronously
-    def invoke(input_state = {}, context: nil, store: nil, thread_id: nil)
+    def invoke(input_state = {}, context: nil, store: nil, thread_id: nil, observers: [])
       raise GraphError, "Graph must be compiled before execution" unless compiled?
       
       store ||= Stores::InMemoryStore.new
@@ -104,11 +104,12 @@ module LangGraphRB
       
       initial_state = @state_class.new(input_state)
       
-      Runner.new(self, store: store, thread_id: thread_id).invoke(initial_state, context: context)
+      Runner.new(self, store: store, thread_id: thread_id, observers: observers)
+        .invoke(initial_state, context: context)
     end
 
     # Stream execution results
-    def stream(input_state = {}, context: nil, store: nil, thread_id: nil)
+    def stream(input_state = {}, context: nil, store: nil, thread_id: nil, observers: [])
       raise GraphError, "Graph must be compiled before execution" unless compiled?
       
       store ||= Stores::InMemoryStore.new
@@ -116,7 +117,8 @@ module LangGraphRB
       
       initial_state = @state_class.new(input_state)
       
-      Runner.new(self, store: store, thread_id: thread_id).stream(initial_state, context: context)
+      Runner.new(self, store: store, thread_id: thread_id, observers: observers)
+        .stream(initial_state, context: context)
     end
 
     # Resume execution from a checkpoint

data/lib/langgraph_rb/observers/base.rb

@@ -0,0 +1,188 @@
+require 'json'
+require 'time'
+
+module LangGraphRB
+  module Observers
+    # Abstract base class for observability implementations
+    class BaseObserver
+      # Called when graph execution starts
+      def on_graph_start(event)
+        # Override in subclasses
+      end
+
+      # Called when graph execution completes
+      def on_graph_end(event)
+        # Override in subclasses
+      end
+
+      # Called when a node execution starts
+      def on_node_start(event)
+        # Override in subclasses
+      end
+
+      # Called when a node execution completes successfully
+      def on_node_end(event)
+        # Override in subclasses
+      end
+
+      # Called when a node execution encounters an error
+      def on_node_error(event)
+        # Override in subclasses
+      end
+
+      # Called when a step completes (multiple nodes may execute in parallel)
+      def on_step_complete(event)
+        # Override in subclasses
+      end
+
+      # Called when state changes occur
+      def on_state_change(event)
+        # Override in subclasses
+      end
+
+      # Called when commands are processed (Send, Command, etc.)
+      def on_command_processed(event)
+        # Override in subclasses
+      end
+
+      # Called when interrupts occur
+      def on_interrupt(event)
+        # Override in subclasses
+      end
+
+      # Called when checkpoints are saved
+      def on_checkpoint_saved(event)
+        # Override in subclasses
+      end
+
+      # Shutdown hook for cleanup
+      def shutdown
+        # Override in subclasses if cleanup needed
+      end
+
+      protected
+
+      # Helper method to create standardized event structure
+      def create_event(type, data = {})
+        {
+          type: type,
+          timestamp: Time.now.utc.iso8601,
+          thread_id: data[:thread_id],
+          step_number: data[:step_number],
+          **data
+        }
+      end
+
+      # Helper to sanitize state data (remove sensitive info, limit size)
+      def sanitize_state(state, max_size: 1000)
+        return nil unless state
+        
+        state_hash = state.respond_to?(:to_h) ? state.to_h : state
+        serialized = state_hash.to_json
+        
+        if serialized.length > max_size
+          { _truncated: true, _size: serialized.length, _preview: serialized[0...max_size] }
+        else
+          state_hash
+        end
+      end
+    end
+
+    # Event data structures
+    class GraphEvent
+      attr_reader :type, :graph, :initial_state, :context, :thread_id, :timestamp
+
+      def initialize(type:, graph:, initial_state: nil, context: nil, thread_id: nil)
+        @type = type
+        @graph = graph
+        @initial_state = initial_state
+        @context = context
+        @thread_id = thread_id
+        @timestamp = Time.now.utc
+      end
+
+      def to_h
+        {
+          type: @type,
+          graph_class: @graph.class.name,
+          node_count: @graph.nodes.size,
+          edge_count: @graph.edges.size,
+          initial_state: @initial_state,
+          context: @context,
+          thread_id: @thread_id,
+          timestamp: @timestamp.iso8601
+        }
+      end
+    end
+
+    class NodeEvent
+      attr_reader :type, :node_name, :node_class, :state_before, :state_after, 
+                  :context, :thread_id, :step_number, :duration, :error, :result, :timestamp
+
+      def initialize(type:, node_name:, node_class: nil, state_before: nil, state_after: nil,
+                     context: nil, thread_id: nil, step_number: nil, duration: nil, 
+                     error: nil, result: nil)
+        @type = type
+        @node_name = node_name
+        @node_class = node_class
+        @state_before = state_before
+        @state_after = state_after
+        @context = context
+        @thread_id = thread_id
+        @step_number = step_number
+        @duration = duration
+        @error = error
+        @result = result
+        @timestamp = Time.now.utc
+      end
+
+      def to_h
+        {
+          type: @type,
+          node_name: @node_name,
+          node_class: @node_class&.name,
+          state_before: @state_before,
+          state_after: @state_after,
+          context: @context,
+          thread_id: @thread_id,
+          step_number: @step_number,
+          duration_ms: @duration ? (@duration * 1000).round(2) : nil,
+          error: @error&.message,
+          error_class: @error&.class&.name,
+          result_type: @result&.class&.name,
+          timestamp: @timestamp.iso8601
+        }
+      end
+    end
+
+    class StepEvent
+      attr_reader :type, :step_number, :active_nodes, :completed_nodes, :thread_id, 
+                  :state, :duration, :timestamp
+
+      def initialize(type:, step_number:, active_nodes: [], completed_nodes: [], 
+                     thread_id: nil, state: nil, duration: nil)
+        @type = type
+        @step_number = step_number
+        @active_nodes = active_nodes
+        @completed_nodes = completed_nodes
+        @thread_id = thread_id
+        @state = state
+        @duration = duration
+        @timestamp = Time.now.utc
+      end
+
+      def to_h
+        {
+          type: @type,
+          step_number: @step_number,
+          active_nodes: @active_nodes,
+          completed_nodes: @completed_nodes,
+          thread_id: @thread_id,
+          state: @state,
+          duration_ms: @duration ? (@duration * 1000).round(2) : nil,
+          timestamp: @timestamp.iso8601
+        }
+      end
+    end
+  end
+end