flow_nodes 0.1.0

data/lib/flow_nodes/async_node.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # A node designed for asynchronous execution.
+  class AsyncNode < Node
+    # Runs the node asynchronously. Use with `AsyncFlow` to chain successors.
+    def run_async(s)
+      warn("Node won't run successors. Use AsyncFlow.") unless @successors.empty?
+      _run_async(s)
+    end
+
+    def _run(_s)
+      raise "Use run_async for AsyncNode."
+    end
+
+    protected
+
+    def prep_async(_s) = nil
+    def exec_async(_p) = nil
+    def post_async(_s, _p, _e) = nil
+
+    def exec_fallback_async(p, exc)
+      exec_fallback(p, exc)
+    end
+
+    def _exec_async(p)
+      last_exception = nil
+      @max_retries.times do |i|
+        @current_retry = i
+        begin
+          return exec_async(p)
+        rescue StandardError => e
+          last_exception = e
+          sleep @wait if @wait.positive? && i < @max_retries - 1
+        end
+      end
+      exec_fallback_async(p, last_exception)
+    end
+
+    def _run_async(s)
+      prepared_params = prep_async(s)
+      actual_params = prepared_params || @params
+      result = _exec_async(actual_params)
+      post_async(s, actual_params, result)
+      result
+    end
+  end
+end

data/lib/flow_nodes/async_parallel_batch_flow.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # An async flow that processes a batch of items in parallel using threads.
+  class AsyncParallelBatchFlow < AsyncFlow
+    protected
+
+    def _run_async(s)
+      batch_params = prep_async(s) || []
+      threads = batch_params.map do |item_params|
+        Thread.new { _orch_async(s, params: @params.merge(item_params)) }
+      end
+      threads.map(&:value)
+      post_async(s, batch_params, nil)
+    end
+  end
+end

data/lib/flow_nodes/async_parallel_batch_node.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # An async node that processes a batch of items in parallel using threads.
+  class AsyncParallelBatchNode < AsyncNode
+    protected
+
+    # @note This uses standard Ruby threads and is subject to the Global VM Lock (GVL).
+    # It is best suited for I/O-bound tasks, not for parallelizing CPU-bound work.
+    def _exec_async(items)
+      return [] if items.nil?
+
+      items_array = items.is_a?(Array) ? items : [items]
+      threads = items_array.map { |item| Thread.new { super(item) } }
+      threads.map(&:value)
+    end
+  end
+end

data/lib/flow_nodes/base_node.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # Base class for all nodes in a flow. Defines the core API for connecting
+  # nodes and executing logic.
+  class BaseNode
+    # @return [Hash] parameters passed to the node during execution.
+    attr_accessor :params
+
+    # @return [Hash<String, BaseNode>] a hash mapping action names to successor nodes.
+    attr_accessor :successors
+
+    def initialize
+      @params = {}
+      @successors = {}
+    end
+
+    # Creates a deep copy of the node. This is critical for ensuring that each
+    # execution of a flow operates on its own isolated set of node instances,
+    # preventing state bleed.
+    #
+    # @param other [BaseNode] The original node being duplicated.
+    def initialize_copy(other)
+      super
+      @params = Marshal.load(Marshal.dump(other.params))
+      # Successors are other nodes. The orchestration loop handles duplicating them
+      # as they are traversed. A shallow copy of the hash is sufficient here.
+      @successors = other.successors.dup
+    end
+
+    # Sets the parameters for the node. To ensure thread safety and prevent
+    # state bleed, the parameters are deep-copied.
+    #
+    # @param p [Hash] The parameters to set.
+    def set_params(p)
+      @params = Marshal.load(Marshal.dump(p || {}))
+    end
+
+    # Connects this node to a successor for a given action.
+    #
+    # @param node [BaseNode] The successor node.
+    # @param action [String] The action name that triggers the transition.
+    # @return [BaseNode] The successor node.
+    def nxt(node, action = "default")
+      warn("Overwriting successor for action '#{action}'") if @successors.key?(action)
+      @successors[action] = node
+      node
+    end
+    alias next nxt
+
+    # Defines the default transition to the next node.
+    # @param other [BaseNode] The node to transition to.
+    def >>(other)
+      nxt(other)
+    end
+
+    # Creates a conditional transition to a successor node.
+    # @param action [String, Symbol] The action that triggers this transition.
+    # @return [ConditionalTransition] An object to define the target node.
+    def -(other)
+      raise TypeError, "Action must be a String or Symbol" unless other.is_a?(String) || other.is_a?(Symbol)
+
+      ConditionalTransition.new(self, other.to_s)
+    end
+
+    # Executes the main logic of the node.
+    # This is intended to be overridden by subclasses.
+    #
+    # @param _p [Hash] The parameters for execution.
+    # @return [String, Symbol, nil] The result action to determine the next node in a flow.
+    def exec(_p)
+      nil
+    end
+
+    # Runs the full lifecycle of the node: prep, exec, and post.
+    # If not part of a Flow, successors will not be executed.
+    #
+    # @param state [Object] An optional shared state object passed through the flow.
+    def run(state)
+      warn("Node won't run successors. Use Flow.") unless @successors.empty?
+      _run(state)
+    end
+
+    protected
+
+    # Pre-execution hook. Can be used to prepare data.
+    # @param _state [Object] The shared state object.
+    def prep(_state)
+      nil
+    end
+
+    # Post-execution hook. Can be used for cleanup or logging.
+    # @param _state [Object] The shared state object.
+    # @param _params [Hash] The parameters used in execution.
+    # @param _result [Object] The value returned by `exec`.
+    def post(_state, _params, _result)
+      nil
+    end
+
+    # Internal execution wrapper.
+    # @param p [Hash] The parameters for execution.
+    def _exec(p)
+      exec(p)
+    end
+
+    # Internal run lifecycle.
+    # @param s [Object] The shared state object.
+    def _run(s)
+      prepared_params = prep(s)
+      # Use the node's params if prep returns nil
+      params_to_use = prepared_params || @params
+      execution_result = _exec(params_to_use)
+      post(s, prepared_params, execution_result)
+      execution_result
+    end
+  end
+end

data/lib/flow_nodes/batch_flow.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # A flow that processes a batch of items sequentially.
+  class BatchFlow < Flow
+    protected
+
+    def _run(s)
+      batch_params = prep(s) || []
+      batch_params.each do |item_params|
+        _orch(@params.merge(item_params))
+      end
+      post(s, batch_params, nil)
+    end
+  end
+end

data/lib/flow_nodes/batch_node.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # A node that processes a batch of items sequentially.
+  class BatchNode < Node
+    protected
+
+    def _exec(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/conditional_transition.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # Represents a pending conditional transition from one node to another.
+  class ConditionalTransition
+    def initialize(source_node, action)
+      @source_node = source_node
+      @action = action
+    end
+
+    # Completes the transition by connecting the source node to the target.
+    # @param target_node [BaseNode] The node to transition to.
+    def >>(other)
+      @source_node.nxt(other, @action)
+    end
+  end
+end

data/lib/flow_nodes/flow.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # Orchestrates a sequence of connected nodes, managing state and transitions.
+  class Flow < BaseNode
+    attr_accessor :start_node
+
+    def initialize(start: nil)
+      super()
+      @start_node = start
+    end
+
+    # Sets the starting node of the flow.
+    # @param node [BaseNode] The node to start the flow with.
+    # @return [BaseNode] The starting node.
+    def start(node)
+      @start_node = node
+      node
+    end
+
+    protected
+
+    # Main orchestration logic that walks through the node graph.
+    def _orch(initial_params)
+      raise "Flow has no start node" unless @start_node
+
+      current_node = @start_node.dup
+      current_params = initial_params
+
+      loop do
+        # Merge the node's own params with the incoming params from the flow.
+        # The flow's params take precedence.
+        merged_params = current_node.params.merge(current_params || {})
+        current_node.set_params(merged_params)
+        current_params = merged_params # Ensure current_params is updated for the next iteration
+
+        action = current_node._run(current_node.params)
+
+        # If the node returns a symbol, it's an action to determine the next node.
+        current_node = get_next_node(current_node, action)&.dup
+        break unless current_node
+      end
+    end
+
+    def _run(s)
+      prepared_params = prep(s)
+      result = _orch(prepared_params || @params)
+      post(s, prepared_params, result)
+      result
+    end
+
+    # Determines the next node based on the result of the current node.
+    # For routing to work predictably, the return value of a node's `exec` method
+    # should be a String or Symbol that matches a defined successor action.
+    def get_next_node(current_node, action)
+      action_key = action.nil? || action == "" ? "default" : action.to_s
+      successor = current_node.successors[action_key]
+
+      if !successor && !current_node.successors.empty?
+        warn("Flow ends: action '#{action_key}' not found in successors: #{current_node.successors.keys.inspect}")
+      end
+      successor
+    end
+  end
+end

data/lib/flow_nodes/node.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  # A node with built-in retry logic.
+  class Node < BaseNode
+    attr_reader :max_retries, :wait, :current_retry
+
+    def initialize(max_retries: 1, wait: 0)
+      super()
+      @max_retries = max_retries
+      @wait = wait
+      @current_retry = 0
+    end
+
+    # Public method to execute the node's logic with retries.
+    # This is the entry point for a flow to run a node.
+    def _run(s)
+      prepared_params = prep(s)
+      actual_params = prepared_params || @params
+      execution_result = _exec(actual_params)
+      post(s, actual_params, execution_result)
+      execution_result
+    end
+
+    protected
+
+    # Internal execution logic with retries.
+    # @note If your `exec` method performs actions with side effects (e.g., API calls,
+    #   database writes), ensure they are idempotent. Retries will re-execute the logic,
+    #   which could cause unintended repeated effects if not designed carefully.
+    def _exec(p)
+      last_exception = nil
+      @max_retries.times do |i|
+        @current_retry = i
+        begin
+          return exec(p)
+        rescue StandardError => e
+          last_exception = e
+          sleep @wait if @wait.positive? && i < @max_retries - 1
+        end
+      end
+      exec_fallback(p, last_exception)
+    end
+
+    # Fallback method called after all retries have been exhausted.
+    # The default behavior is to re-raise the last exception.
+    #
+    # @param _params [Hash] The parameters that caused the failure.
+    # @param exception [Exception] The last exception that was caught.
+    def exec_fallback(_params, exception)
+      raise exception
+    end
+  end
+end

data/lib/flow_nodes/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FlowNodes
+  VERSION = "0.1.0"
+end

data/lib/flow_nodes.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "flow_nodes/version"
+require_relative "flow_nodes/base_node"
+require_relative "flow_nodes/conditional_transition"
+require_relative "flow_nodes/node"
+require_relative "flow_nodes/batch_node"
+require_relative "flow_nodes/flow"
+require_relative "flow_nodes/batch_flow"
+require_relative "flow_nodes/async_node"
+require_relative "flow_nodes/async_batch_node"
+require_relative "flow_nodes/async_parallel_batch_node"
+require_relative "flow_nodes/async_flow"
+require_relative "flow_nodes/async_batch_flow"
+require_relative "flow_nodes/async_parallel_batch_flow"
+
+# FlowNodes is a minimalist, graph-based framework for building complex workflows
+# and agentic systems in Ruby. It is a port of the Python PocketFlow library.
+module FlowNodes
+end

data/sig/flow_nodes.rbs

@@ -0,0 +1,4 @@
+module FlowNodes
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: flow_nodes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- RJ Robinson
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-07-17 00:00:00.000000000 Z
+dependencies: []
+description: FlowNodes is a Ruby port of PocketFlow, the Python framework created
+  by The Pocket. It brings the power and simplicity of PocketFlow's graph-based architecture
+  to the Ruby ecosystem. Build powerful LLM applications like Agents, Workflows, and
+  RAG systems with minimal code and maximum expressiveness.
+email:
+- rj@trainual.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".qlty.yml"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/advanced_workflow.rb
+- examples/batch_processing.rb
+- examples/chatbot.rb
+- examples/llm_calendar_parser.rb
+- examples/llm_content_processor.rb
+- examples/llm_document_analyzer.rb
+- examples/simple_llm_example.rb
+- examples/workflow.rb
+- lib/flow_nodes.rb
+- lib/flow_nodes/async_batch_flow.rb
+- lib/flow_nodes/async_batch_node.rb
+- lib/flow_nodes/async_flow.rb
+- lib/flow_nodes/async_node.rb
+- lib/flow_nodes/async_parallel_batch_flow.rb
+- lib/flow_nodes/async_parallel_batch_node.rb
+- lib/flow_nodes/base_node.rb
+- lib/flow_nodes/batch_flow.rb
+- lib/flow_nodes/batch_node.rb
+- lib/flow_nodes/conditional_transition.rb
+- lib/flow_nodes/flow.rb
+- lib/flow_nodes/node.rb
+- lib/flow_nodes/version.rb
+- sig/flow_nodes.rbs
+homepage: https://github.com/rjrobinson/flow_nodes
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rjrobinson/flow_nodes
+  source_code_uri: https://github.com/rjrobinson/flow_nodes
+  changelog_uri: https://github.com/rjrobinson/flow_nodes/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Ruby port of PocketFlow, the minimalist LLM framework.
+test_files: []