langgraph_rb 0.1.0

data/lib/langgraph_rb/runner.rb

@@ -0,0 +1,360 @@
+require 'thread'
+
+module LangGraphRB
+  class Runner
+    attr_reader :graph, :store, :thread_id
+
+    def initialize(graph, store:, thread_id:)
+      @graph = graph
+      @store = store
+      @thread_id = thread_id
+      @step_number = 0
+      @execution_queue = Queue.new
+      @interrupt_handler = nil
+    end
+
+    # Synchronous execution
+    def invoke(initial_state, context: nil)
+      result = nil
+      
+      stream(initial_state, context: context) do |step_result|
+        result = step_result
+      end
+      
+      result[:state]
+    end
+
+    # Streaming execution with optional block for receiving intermediate results
+    def stream(initial_state, context: nil, &block)
+      @step_number = 0
+      current_state = initial_state
+      
+      # Initialize execution queue with START node
+      active_executions = [
+        ExecutionFrame.new(Graph::START, current_state, 0)
+      ]
+
+      loop do
+        break if active_executions.empty?
+        
+        # Execute current super-step (all nodes at current level in parallel)
+        step_results = execute_super_step(active_executions, context)
+        break if step_results.empty?
+        
+        @step_number += 1
+        
+        # Process results and determine next nodes
+        next_active = []
+        final_state = nil
+        
+        step_results.each do |result|
+          case result[:type]
+          when :completed
+            # Node completed normally
+            if result[:next_destination]
+              # Command specified explicit destination
+              dest_name = result[:next_destination]
+              dest_state = result[:state]
+              
+              if dest_name == Graph::FINISH
+                final_state = dest_state
+              else
+                next_active << ExecutionFrame.new(dest_name, dest_state, @step_number)
+              end
+            else
+              # Use normal edge routing
+              next_destinations = determine_next_destinations(
+                result[:node_name], 
+                result[:state], 
+                context
+              )
+              
+              next_destinations.each do |dest_name, dest_state|
+                if dest_name == Graph::FINISH
+                  final_state = dest_state
+                else
+                  next_active << ExecutionFrame.new(dest_name, dest_state, @step_number)
+                end
+              end
+            end
+            
+          when :send
+            # Handle Send commands (map-reduce)
+            result[:sends].each do |send_cmd|
+              payload_state = result[:state].merge_delta(send_cmd.payload)
+              next_active << ExecutionFrame.new(send_cmd.to, payload_state, @step_number)
+            end
+            
+          when :interrupt
+            # Handle human-in-the-loop interrupts
+            if @interrupt_handler
+              user_input = @interrupt_handler.call(result[:interrupt])
+              # Continue with user input merged into state
+              updated_state = result[:state].merge_delta(user_input || {})
+              next_active << ExecutionFrame.new(result[:node_name], updated_state, @step_number)
+            else
+              # No interrupt handler, treat as completion
+              final_state = result[:state]
+            end
+            
+          when :error
+            raise result[:error]
+          end
+        end
+        
+        # Save checkpoint
+        checkpoint_state = final_state || (next_active.first&.state) || current_state
+        save_checkpoint(checkpoint_state, @step_number)
+        
+        # Yield intermediate result if block given
+        if block
+          yield({
+            step: @step_number,
+            state: checkpoint_state,
+            active_nodes: next_active.map(&:node_name),
+            completed: next_active.empty?
+          })
+        end
+        
+        # Update for next iteration
+        current_state = checkpoint_state
+        active_executions = next_active
+        
+        # Break if we reached END
+        break if final_state
+      end
+      
+      {
+        state: current_state,
+        step_number: @step_number,
+        thread_id: @thread_id
+      }
+    end
+
+    # Resume from checkpoint
+    def resume(additional_input = {}, context: nil)
+      checkpoint = @store.load(@thread_id)
+      raise GraphError, "No checkpoint found for thread #{@thread_id}" unless checkpoint
+      
+      @step_number = checkpoint[:step_number]
+      resumed_state = checkpoint[:state].merge_delta(additional_input)
+      
+      # Resume execution from where we left off
+      stream(resumed_state, context: context)
+    end
+
+    # Set interrupt handler for human-in-the-loop
+    def on_interrupt(&handler)
+      @interrupt_handler = handler
+    end
+
+    private
+
+    # Execute all nodes in the current super-step in parallel
+    def execute_super_step(active_executions, context)
+      return [] if active_executions.empty?
+      
+      # Group by node name to handle potential duplicates
+      grouped_executions = active_executions.group_by(&:node_name)
+      
+      results = []
+      threads = []
+      
+      grouped_executions.each do |node_name, executions|
+        node = @graph.nodes[node_name]
+        next unless node  # Skip if node doesn't exist
+        
+        # Execute each frame for this node
+        executions.each do |frame|
+          thread = Thread.new do
+            execute_node_safely(node, frame.state, context, frame.step)
+          end
+          threads << thread
+        end
+      end
+      
+      # Wait for all threads to complete
+      threads.each do |thread|
+        result = thread.join.value
+        results << result if result
+      end
+      
+      results
+    end
+
+    # Safely execute a single node
+    def execute_node_safely(node, state, context, step)
+      begin
+        result = node.call(state, context: context)
+        process_node_result(node.name, state, result, step)
+      rescue => error
+        {
+          type: :error,
+          node_name: node.name,
+          state: state,
+          step: step,
+          error: error
+        }
+      end
+    end
+
+    # Process the result from a node execution
+    def process_node_result(node_name, original_state, result, step)
+      case result
+      when Command
+        # Handle Command (update + goto)
+        updated_state = original_state.merge_delta(result.update)
+        
+        if result.goto
+          determine_next_destinations(node_name, updated_state, nil, forced_destination: result.goto)
+            .map do |dest_name, dest_state|
+              {
+                type: :completed,
+                node_name: node_name,
+                state: dest_state,
+                step: step,
+                next_destination: dest_name
+              }
+            end.first
+        else
+          {
+            type: :completed,
+            node_name: node_name,
+            state: updated_state,
+            step: step
+          }
+        end
+        
+      when Send
+        # Handle single Send
+        {
+          type: :send,
+          node_name: node_name,
+          state: original_state,
+          step: step,
+          sends: [result]
+        }
+        
+      when MultiSend
+        # Handle multiple Sends
+        {
+          type: :send,
+          node_name: node_name,
+          state: original_state,
+          step: step,
+          sends: result.sends
+        }
+        
+      when Interrupt
+        # Handle interrupt for human-in-the-loop
+        {
+          type: :interrupt,
+          node_name: node_name,
+          state: original_state,
+          step: step,
+          interrupt: result
+        }
+        
+      when Hash
+        # Handle simple state delta
+        updated_state = original_state.merge_delta(result)
+        {
+          type: :completed,
+          node_name: node_name,
+          state: updated_state,
+          step: step
+        }
+        
+      else
+        # Handle other return values
+        {
+          type: :completed,
+          node_name: node_name,
+          state: original_state,
+          step: step
+        }
+      end
+    end
+
+    # Determine next destinations based on edges
+    def determine_next_destinations(from_node, state, context, forced_destination: nil)
+      if forced_destination
+        return [[forced_destination, state]]
+      end
+      
+      edges = @graph.get_edges_from(from_node)
+      destinations = []
+      
+      edges.each do |edge|
+        case edge
+        when Edge
+          destinations << [edge.to, state]
+          
+        when ConditionalEdge
+          routes = edge.route(state, context: context)
+          routes.each do |dest|
+            destinations << [dest, state]
+          end
+          
+        when FanOutEdge
+          routes = edge.route(state, context: context)
+          routes.each do |dest|
+            destinations << [dest, state]
+          end
+        end
+      end
+      
+      # Default to FINISH if no edges defined
+      destinations.empty? ? [[Graph::FINISH, state]] : destinations
+    end
+
+    # Save execution checkpoint
+    def save_checkpoint(state, step_number)
+      @store.save(@thread_id, state, step_number, {
+        timestamp: Time.now,
+        graph_class: @graph.class.name
+      })
+    end
+
+    # Execution frame for tracking active node executions
+    class ExecutionFrame
+      attr_reader :node_name, :state, :step
+
+      def initialize(node_name, state, step)
+        @node_name = node_name.to_sym
+        @state = state
+        @step = step
+      end
+
+      def to_s
+        "#<ExecutionFrame node: #{@node_name}, step: #{@step}>"
+      end
+    end
+  end
+
+  # Thread-safe execution result collector
+  class ResultCollector
+    def initialize
+      @results = []
+      @mutex = Mutex.new
+    end
+
+    def add(result)
+      @mutex.synchronize do
+        @results << result
+      end
+    end
+
+    def all
+      @mutex.synchronize do
+        @results.dup
+      end
+    end
+
+    def clear
+      @mutex.synchronize do
+        @results.clear
+      end
+    end
+  end
+end 

data/lib/langgraph_rb/state.rb

@@ -0,0 +1,70 @@
+module LangGraphRB
+  class State < Hash
+    attr_reader :reducers
+
+    def initialize(schema = {}, reducers = {})
+      @reducers = reducers || {}
+      super()
+      merge!(schema) if schema.is_a?(Hash)
+    end
+
+    # Merge a delta (partial state update) using reducers
+    def merge_delta(delta)
+      return self if delta.nil? || delta.empty?
+      
+      new_state = self.class.new({}, @reducers)
+      new_state.merge!(self)
+      
+      delta.each do |key, value|
+        key = key.to_sym
+        
+        if @reducers[key]
+          # Use the reducer function to combine old and new values
+          new_state[key] = @reducers[key].call(self[key], value)
+        else
+          # Simple replacement
+          new_state[key] = value
+        end
+      end
+      
+      new_state
+    end
+
+    # Create a new state with additional reducers
+    def with_reducers(new_reducers)
+      self.class.new(self, @reducers.merge(new_reducers))
+    end
+
+    # Common reducer for adding messages to an array
+    def self.add_messages
+      ->(old_value, new_value) do
+        old_array = old_value || []
+        new_array = new_value.is_a?(Array) ? new_value : [new_value]
+        old_array + new_array
+      end
+    end
+
+    # Common reducer for appending strings
+    def self.append_string
+      ->(old_value, new_value) do
+        (old_value || "") + new_value.to_s
+      end
+    end
+
+    # Common reducer for merging hashes
+    def self.merge_hash
+      ->(old_value, new_value) do
+        old_hash = old_value || {}
+        old_hash.merge(new_value || {})
+      end
+    end
+
+    def to_h
+      Hash[self]
+    end
+
+    def inspect
+      "#<#{self.class.name} #{super}>"
+    end
+  end
+end 

data/lib/langgraph_rb/stores/memory.rb

@@ -0,0 +1,265 @@
+require 'json'
+require 'yaml'
+require 'fileutils'
+
+module LangGraphRB
+  module Stores
+    # Abstract base class for memory stores
+    class BaseStore
+      def save(thread_id, state, step_number, metadata = {})
+        raise NotImplementedError, "Subclasses must implement #save"
+      end
+
+      def load(thread_id, step_number = nil)
+        raise NotImplementedError, "Subclasses must implement #load"
+      end
+
+      def list_threads
+        raise NotImplementedError, "Subclasses must implement #list_threads"
+      end
+
+      def delete(thread_id)
+        raise NotImplementedError, "Subclasses must implement #delete"
+      end
+
+      def list_steps(thread_id)
+        raise NotImplementedError, "Subclasses must implement #list_steps"
+      end
+    end
+
+    # In-memory store (not persistent across process restarts)
+    class InMemoryStore < BaseStore
+      def initialize
+        @data = {}
+      end
+
+      def save(thread_id, state, step_number, metadata = {})
+        @data[thread_id] ||= {}
+        @data[thread_id][step_number] = {
+          state: deep_copy(state),
+          timestamp: Time.now,
+          metadata: metadata
+        }
+      end
+
+      def load(thread_id, step_number = nil)
+        thread_data = @data[thread_id]
+        return nil unless thread_data
+
+        if step_number
+          checkpoint = thread_data[step_number]
+          return nil unless checkpoint
+          
+          {
+            state: deep_copy(checkpoint[:state]),
+            step_number: step_number,
+            timestamp: checkpoint[:timestamp],
+            metadata: checkpoint[:metadata]
+          }
+        else
+          # Return latest checkpoint
+          latest_step = thread_data.keys.max
+          return nil unless latest_step
+          
+          checkpoint = thread_data[latest_step]
+          {
+            state: deep_copy(checkpoint[:state]),
+            step_number: latest_step,
+            timestamp: checkpoint[:timestamp],
+            metadata: checkpoint[:metadata]
+          }
+        end
+      end
+
+      def list_threads
+        @data.keys
+      end
+
+      def delete(thread_id)
+        @data.delete(thread_id)
+      end
+
+      def list_steps(thread_id)
+        thread_data = @data[thread_id]
+        return [] unless thread_data
+
+        thread_data.keys.sort
+      end
+
+      def clear
+        @data.clear
+      end
+
+      private
+
+      def deep_copy(obj)
+        case obj
+        when Hash
+          obj.transform_values { |v| deep_copy(v) }
+        when Array
+          obj.map { |v| deep_copy(v) }
+        else
+          obj.dup rescue obj
+        end
+      end
+    end
+
+    # File-based store using YAML
+    class FileStore < BaseStore
+      def initialize(base_path)
+        @base_path = base_path
+        FileUtils.mkdir_p(@base_path) unless Dir.exist?(@base_path)
+      end
+
+      def save(thread_id, state, step_number, metadata = {})
+        thread_dir = File.join(@base_path, thread_id.to_s)
+        FileUtils.mkdir_p(thread_dir) unless Dir.exist?(thread_dir)
+
+        checkpoint_file = File.join(thread_dir, "#{step_number}.yml")
+        
+        data = {
+          state: state.to_h,
+          timestamp: Time.now,
+          metadata: metadata
+        }
+
+        File.write(checkpoint_file, YAML.dump(data))
+      end
+
+      def load(thread_id, step_number = nil)
+        thread_dir = File.join(@base_path, thread_id.to_s)
+        return nil unless Dir.exist?(thread_dir)
+
+        if step_number
+          checkpoint_file = File.join(thread_dir, "#{step_number}.yml")
+          return nil unless File.exist?(checkpoint_file)
+
+          data = YAML.load_file(checkpoint_file)
+          {
+            state: State.new(data['state']),
+            step_number: step_number,
+            timestamp: data['timestamp'],
+            metadata: data['metadata'] || {}
+          }
+        else
+          # Find latest checkpoint
+          files = Dir.glob(File.join(thread_dir, "*.yml"))
+          return nil if files.empty?
+
+          latest_file = files.max_by do |file|
+            File.basename(file, '.yml').to_i
+          end
+
+          step_num = File.basename(latest_file, '.yml').to_i
+          data = YAML.load_file(latest_file)
+          
+          {
+            state: State.new(data['state']),
+            step_number: step_num,
+            timestamp: data['timestamp'],
+            metadata: data['metadata'] || {}
+          }
+        end
+      end
+
+      def list_threads
+        Dir.entries(@base_path).select do |entry|
+          File.directory?(File.join(@base_path, entry)) && entry != '.' && entry != '..'
+        end
+      end
+
+      def delete(thread_id)
+        thread_dir = File.join(@base_path, thread_id.to_s)
+        FileUtils.rm_rf(thread_dir) if Dir.exist?(thread_dir)
+      end
+
+      def list_steps(thread_id)
+        thread_dir = File.join(@base_path, thread_id.to_s)
+        return [] unless Dir.exist?(thread_dir)
+
+        Dir.glob(File.join(thread_dir, "*.yml")).map do |file|
+          File.basename(file, '.yml').to_i
+        end.sort
+      end
+    end
+
+    # JSON-based store
+    class JsonStore < BaseStore
+      def initialize(base_path)
+        @base_path = base_path
+        FileUtils.mkdir_p(@base_path) unless Dir.exist?(@base_path)
+      end
+
+      def save(thread_id, state, step_number, metadata = {})
+        thread_dir = File.join(@base_path, thread_id.to_s)
+        FileUtils.mkdir_p(thread_dir) unless Dir.exist?(thread_dir)
+
+        checkpoint_file = File.join(thread_dir, "#{step_number}.json")
+        
+        data = {
+          state: state.to_h,
+          timestamp: Time.now.iso8601,
+          metadata: metadata
+        }
+
+        File.write(checkpoint_file, JSON.pretty_generate(data))
+      end
+
+      def load(thread_id, step_number = nil)
+        thread_dir = File.join(@base_path, thread_id.to_s)
+        return nil unless Dir.exist?(thread_dir)
+
+        if step_number
+          checkpoint_file = File.join(thread_dir, "#{step_number}.json")
+          return nil unless File.exist?(checkpoint_file)
+
+          data = JSON.parse(File.read(checkpoint_file))
+          {
+            state: State.new(data['state']),
+            step_number: step_number,
+            timestamp: Time.parse(data['timestamp']),
+            metadata: data['metadata'] || {}
+          }
+        else
+          # Find latest checkpoint
+          files = Dir.glob(File.join(thread_dir, "*.json"))
+          return nil if files.empty?
+
+          latest_file = files.max_by do |file|
+            File.basename(file, '.json').to_i
+          end
+
+          step_num = File.basename(latest_file, '.json').to_i
+          data = JSON.parse(File.read(latest_file))
+          
+          {
+            state: State.new(data['state']),
+            step_number: step_num,
+            timestamp: Time.parse(data['timestamp']),
+            metadata: data['metadata'] || {}
+          }
+        end
+      end
+
+      def list_threads
+        Dir.entries(@base_path).select do |entry|
+          File.directory?(File.join(@base_path, entry)) && entry != '.' && entry != '..'
+        end
+      end
+
+      def delete(thread_id)
+        thread_dir = File.join(@base_path, thread_id.to_s)
+        FileUtils.rm_rf(thread_dir) if Dir.exist?(thread_dir)
+      end
+
+      def list_steps(thread_id)
+        thread_dir = File.join(@base_path, thread_id.to_s)
+        return [] unless Dir.exist?(thread_dir)
+
+        Dir.glob(File.join(thread_dir, "*.json")).map do |file|
+          File.basename(file, '.json').to_i
+        end.sort
+      end
+    end
+  end
+end 

data/lib/langgraph_rb/version.rb

@@ -0,0 +1,3 @@
+module LangGraphRB
+  VERSION = "0.1.0"
+end 

data/lib/langgraph_rb.rb

@@ -0,0 +1,15 @@
+require_relative 'langgraph_rb/version'
+require_relative 'langgraph_rb/state'
+require_relative 'langgraph_rb/node'
+require_relative 'langgraph_rb/edge'
+require_relative 'langgraph_rb/command'
+require_relative 'langgraph_rb/graph'
+require_relative 'langgraph_rb/runner'
+require_relative 'langgraph_rb/stores/memory'
+
+module LangGraphRB
+  class Error < StandardError; end
+  class GraphError < Error; end
+  class NodeError < Error; end
+  class StateError < Error; end
+end