phronomy 0.1.4 → 0.2.0

data/lib/phronomy/graph/parallel_node.rb

@@ -1,193 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Graph
-    # Represents a set of branches that execute concurrently as a single graph node.
-    #
-    # Each branch is a callable (Proc, lambda, or any object responding to #call)
-    # that receives the current state and returns either a Hash of field updates or
-    # nil.  All branches run in separate threads; their results are merged in
-    # registration order using the following policy:
-    #
-    #   :replace fields  — last-write-wins (rightmost branch wins)
-    #   :append  fields  — all Arrays are concatenated
-    #   :merge   fields  — all Hashes are deep-merged (rightmost wins on conflict)
-    #
-    # @example Basic two-branch node
-    #   graph.add_parallel_node(:step,
-    #     ->(state) { { field_a: "from_a" } },
-    #     ->(state) { { field_b: "from_b" } }
-    #   )
-    #
-    # @example With timeout and failure policy
-    #   graph.add_parallel_node(:step,
-    #     branch_a, branch_b,
-    #     timeout: 10,
-    #     on_error: :best_effort
-    #   )
-    #
-    # Timeout support
-    #   Pass +timeout:+ (seconds, Numeric) to limit how long the node may run.
-    #   If any thread does not finish within the limit, all threads are killed and
-    #   +Phronomy::Graph::TimeoutError+ is raised (for +:raise+ policy) or recorded
-    #   in the result hash under +:parallel_errors+ (for +:best_effort+ policy).
-    #
-    # Failure policies (+on_error:+)
-    #   :raise (default)
-    #     Re-raises the first exception after all threads are joined.
-    #     Mirrors the original Thread#value semantics.
-    #   :best_effort
-    #     Collects successful results and stores any errors in the update Hash
-    #     under the key +:parallel_errors+ (Array of exception objects).
-    #     The caller's state class should declare:
-    #       field :parallel_errors, type: :append, default: -> { [] }
-    #     Unknown keys are silently ignored by the State#merge machinery.
-    class ParallelNode
-      # @param branches  [Array<#call>]     at least one callable branch required
-      # @param timeout   [Numeric, nil]     wall-clock limit in seconds; nil = unlimited
-      # @param on_error  [Symbol]           :raise (default) or :best_effort
-      def initialize(branches, timeout: nil, on_error: :raise)
-        raise ArgumentError, "branches must be a non-empty Array" if branches.empty?
-        unless %i[raise best_effort].include?(on_error)
-          raise ArgumentError, "on_error must be :raise or :best_effort, got #{on_error.inspect}"
-        end
-
-        @branches = branches
-        @timeout = timeout
-        @on_error = on_error
-      end
-
-      # Executes all branches concurrently and merges their results.
-      #
-      # @param state [Object] state object (includes Phronomy::Graph::State)
-      # @return [Hash, nil] merged update hash, or nil when all branches return nil
-      def call(state)
-        threads = @branches.map { |branch| Thread.new { branch.call(state) } }
-        deadline = @timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout) : nil
-        state_class = state.class
-
-        if @on_error == :best_effort
-          gather_best_effort(threads, deadline, state_class)
-        else
-          gather_raise(threads, deadline, state_class)
-        end
-      end
-
-      private
-
-      # Joins all threads, enforcing the deadline. Re-raises branch exceptions.
-      def gather_raise(threads, deadline, state_class)
-        if deadline
-          threads.each do |t|
-            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            next if t.join([remaining, 0].max)
-
-            # Thread did not finish within the time limit.
-            # Use Thread#raise instead of Thread#kill so that ensure blocks in
-            # branches (DB connection return, Mutex release, etc.) are executed.
-            timeout_error = Phronomy::Graph::TimeoutError.new(
-              "parallel branch timed out after #{@timeout}s"
-            )
-            threads.each { |thr| thr.raise(timeout_error) unless thr.stop? }
-            threads.each do |thr|
-              thr.join(0.1)
-            rescue
-              nil
-            end
-            raise Phronomy::Graph::TimeoutError,
-              "parallel branch timed out after #{@timeout}s"
-          end
-        end
-
-        # All threads are done. Thread#value re-raises any stored exception.
-        merge_results(threads.map(&:value), state_class)
-      end
-
-      # Joins all threads, collecting errors instead of re-raising them.
-      def gather_best_effort(threads, deadline, state_class)
-        errors = []
-        results = threads.map do |t|
-          if deadline
-            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            # Thread#join(limit) re-raises the thread's stored exception in the calling
-            # thread when the thread terminated abnormally within the limit.
-            # Rescue here so the error is collected rather than propagated.
-            begin
-              joined = t.join([remaining, 0].max)
-            rescue => e
-              errors << e
-              next nil
-            end
-            if joined.nil?
-              timeout_error = Phronomy::Graph::TimeoutError.new(
-                "branch timed out after #{@timeout}s"
-              )
-              t.raise(timeout_error) unless t.stop?
-              begin
-                t.join(0.1)
-              rescue
-                nil
-              end
-              errors << Phronomy::Graph::TimeoutError.new(
-                "branch timed out after #{@timeout}s"
-              )
-              next nil
-            end
-          end
-
-          begin
-            t.value
-          rescue => e
-            errors << e
-            nil
-          end
-        end
-
-        merged = merge_results(results, state_class) || {}
-        merged[:parallel_errors] = errors unless errors.empty?
-        merged.empty? ? nil : merged
-      end
-
-      # Merges an Array of per-branch result Hashes (nils are skipped).
-      # Field merge policy is determined from the State class field declarations:
-      #   :replace fields  — last-write-wins (rightmost branch wins)
-      #   :append  fields  — all Arrays are concatenated
-      #   :merge   fields  — all Hashes are deep-merged (rightmost wins on conflict)
-      # Unknown / undeclared fields fall back to type-based heuristics.
-      def merge_results(results, state_class = nil)
-        merged = results.compact.each_with_object({}) do |result, acc|
-          next unless result.is_a?(Hash)
-
-          result.each do |key, val|
-            acc[key] = acc.key?(key) ? merge_values(acc[key], val, state_class&.fields&.dig(key, :type)) : val
-          end
-        end
-
-        merged.empty? ? nil : merged
-      end
-
-      # Merges two values for the same state field key across branches.
-      # Uses the declared field policy when available, otherwise falls back to
-      # type-based heuristics (Array → concat, Hash → deep-merge, scalar → last-write-wins).
-      def merge_values(old_val, new_val, policy = nil)
-        case policy
-        when :append
-          (old_val.is_a?(Array) && new_val.is_a?(Array)) ? old_val + new_val : new_val
-        when :merge
-          (old_val.is_a?(Hash) && new_val.is_a?(Hash)) ? old_val.merge(new_val) : new_val
-        when :replace
-          new_val
-        else
-          # Unknown field or no State class: fall back to type-based heuristic.
-          if old_val.is_a?(Array) && new_val.is_a?(Array)
-            old_val + new_val
-          elsif old_val.is_a?(Hash) && new_val.is_a?(Hash)
-            old_val.merge(new_val)
-          else
-            new_val
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/graph/state.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Graph
-    # Module for defining graph state.
-    # Include in a class and use the field DSL to declare state fields.
-    #
-    # Field update policies:
-    #   :replace (default) -- overwrites with the new value
-    #   :append            -- appends to an Array
-    #   :merge             -- deep-merges into a Hash
-    #
-    # @example
-    #   class MyState
-    #     include Phronomy::Graph::State
-    #     field :messages, type: :append, default: -> { [] }
-    #     field :query,    type: :replace
-    #     field :metadata, type: :merge,   default: -> { {} }
-    #   end
-    module State
-      def self.included(base)
-        base.extend(ClassMethods)
-        base.instance_variable_set(:@fields, {})
-      end
-
-      module ClassMethods
-        # Defines a state field.
-        # @param name [Symbol]
-        # @param type [Symbol] :replace / :append / :merge
-        # @param default [Object, Proc, nil]
-        def field(name, type: :replace, default: nil)
-          @fields[name] = {type: type, default: default}
-          attr_accessor name
-        end
-
-        def fields
-          @fields
-        end
-      end
-
-      # Internal graph metadata accessors (not user-defined fields).
-      # These are preserved through merge but excluded from to_h.
-      attr_reader :thread_id, :current_nodes, :halted_before
-
-      # Sets internal graph metadata. Returns self.
-      # @param thread_id [String, nil]
-      # @param current_nodes [Array<Symbol>]
-      # @param halted_before [Boolean]
-      def set_graph_metadata(thread_id: nil, current_nodes: [], halted_before: false)
-        @thread_id = thread_id
-        @current_nodes = current_nodes || []
-        @halted_before = halted_before
-        self
-      end
-
-      def initialize(**attrs)
-        self.class.fields.each do |name, config|
-          default = config[:default].is_a?(Proc) ? config[:default].call : config[:default]
-          send(:"#{name}=", attrs.fetch(name, default))
-        end
-        @thread_id = nil
-        @current_nodes = []
-        @halted_before = false
-      end
-
-      # Immutably updates state fields. Returns a new instance with the applied changes.
-      # Internal graph metadata (thread_id, current_nodes, halted_before) is preserved.
-      # @param updates [Hash] { field_name => new_value }
-      # @return [self.class] new state instance
-      def merge(updates)
-        new_attrs = {}
-        self.class.fields.each_key do |name|
-          field_config = self.class.fields[name]
-          new_attrs[name] = if updates.key?(name)
-            case field_config[:type]
-            when :append
-              Array(send(name)) + Array(updates[name])
-            when :merge
-              (send(name) || {}).merge(updates[name])
-            else
-              updates[name]
-            end
-          else
-            send(name)
-          end
-        end
-        new_state = self.class.new(**new_attrs)
-        new_state.set_graph_metadata(
-          thread_id: @thread_id,
-          current_nodes: @current_nodes,
-          halted_before: @halted_before
-        )
-        new_state
-      end
-
-      # Converts user-defined fields to a Hash (excludes internal graph metadata).
-      # @return [Hash]
-      def to_h
-        self.class.fields.keys.each_with_object({}) do |name, h|
-          h[name] = send(name)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/graph/state_graph.rb

@@ -1,149 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Graph
-    # Declarative agent workflow definition class.
-    # Assembles nodes and edges, then returns an executable CompiledGraph via compile.
-    class StateGraph
-      START = :__start__
-      FINISH = :__end__
-
-      attr_reader :nodes, :edges, :entry_point
-
-      # @param state_class [Class] class that includes Phronomy::Graph::State
-      def initialize(state_class)
-        @state_class = state_class
-        @nodes = {}
-        @edges = {}
-        @conditional_edges = {}
-        @entry_point = nil
-        @before_callbacks = {}
-        @after_callbacks = {}
-      end
-
-      # Adds a node.
-      # @param name [Symbol]
-      # @param callable [#call, nil] node execution logic (block accepted)
-      # @return [self]
-      def add_node(name, callable = nil, &block)
-        @nodes[name] = callable || block
-        self
-      end
-
-      # Adds a directed edge.
-      # @param from [Symbol]
-      # @param to [Symbol]
-      # @param condition [Proc, nil] guard condition — receives state and returns truthy/falsy.
-      #   When nil, the edge is unconditional. When multiple edges exist from the same node,
-      #   they are evaluated in registration order and the first matching edge is taken.
-      # @return [self]
-      def add_edge(from, to, condition = nil)
-        @edges[from] ||= []
-        @edges[from] << {to: to, condition: condition}
-        self
-      end
-
-      # Adds a conditional edge.
-      # @param from [Symbol]
-      # @param condition [Proc] receives state and returns the next node name
-      # @param mapping [Hash, nil] maps condition return value to a node name (optional)
-      # @return [self]
-      def add_conditional_edges(from, condition, mapping = nil)
-        @conditional_edges[from] = {condition: condition, mapping: mapping}
-        self
-      end
-
-      # Sets the entry point node.
-      # @param node_name [Symbol]
-      # @return [self]
-      def set_entry_point(node_name)
-        @entry_point = node_name
-        self
-      end
-
-      # Registers a callback to run before the given node executes.
-      # Return :halt from the block to pause execution; any other value continues.
-      # Callbacks registered here become defaults for every CompiledGraph produced by compile.
-      # @param node [Symbol]
-      # @yield [state] the current state
-      # @return [self]
-      def interrupt_before(node, &block)
-        @before_callbacks[node] = block
-        self
-      end
-
-      # Registers a callback to run after the given node completes.
-      # Return :halt from the block to pause execution; any other value continues.
-      # Callbacks registered here become defaults for every CompiledGraph produced by compile.
-      # @param node [Symbol]
-      # @yield [state] the state after the node ran
-      # @return [self]
-      def interrupt_after(node, &block)
-        @after_callbacks[node] = block
-        self
-      end
-
-      # Adds a parallel node that executes multiple branches concurrently.
-      # Each branch callable receives the current state and must return a Hash or nil.
-      # Results are merged in registration order (see ParallelNode for merge policy).
-      #
-      # @param name     [Symbol]
-      # @param branches [Array<#call>]    at least one callable required
-      # @param timeout  [Numeric, nil]   wall-clock limit in seconds (nil = unlimited)
-      # @param on_error [Symbol]         :raise (default) or :best_effort
-      # @return [self]
-      def add_parallel_node(name, *branches, timeout: nil, on_error: :raise)
-        raise ArgumentError, "add_parallel_node requires at least one branch" if branches.empty?
-
-        @nodes[name] = ParallelNode.new(branches, timeout: timeout, on_error: on_error)
-        self
-      end
-
-      # Embeds a compiled subgraph as a single node in this graph.
-      # The subgraph is invoked with a Hash derived from the parent state;
-      # its final state Hash is returned and merged into the parent state.
-      #
-      # @param name [Symbol]
-      # @param subgraph [CompiledGraph] the compiled subgraph to embed
-      # @param input_mapper  [Proc, nil] maps parent state → input Hash for the subgraph;
-      #   defaults to state.to_h (passes all parent fields)
-      # @param output_mapper [Proc, nil] maps subgraph final state → Hash to merge back;
-      #   defaults to sub_state.to_h (passes all subgraph fields)
-      # @return [self]
-      def add_subgraph(name, subgraph, input_mapper: nil, output_mapper: nil)
-        add_node(name) do |state|
-          input = input_mapper ? input_mapper.call(state) : state.to_h
-          sub_thread_id = "#{state.thread_id}/#{name}"
-          sub_state = subgraph.invoke(input, config: {thread_id: sub_thread_id})
-          output_mapper ? output_mapper.call(sub_state) : sub_state.to_h
-        end
-      end
-
-      # Compiles the graph and returns a CompiledGraph.
-      # Callbacks registered on StateGraph are inherited; additional callbacks can be
-      # registered on the returned CompiledGraph to override or extend them.
-      # @param state_store [Phronomy::StateStore::Base, nil] optional state store
-      #   to use for this compiled graph, overriding the global default.
-      # @return [CompiledGraph]
-      def compile(state_store: nil)
-        if @entry_point.nil? && @nodes.size > 1
-          raise ArgumentError,
-            "set_entry_point was not called; call set_entry_point(:node_name) " \
-            "before compile when the graph has multiple nodes"
-        end
-        CompiledGraph.new(
-          state_class: @state_class,
-          nodes: @nodes,
-          edges: @edges,
-          conditional_edges: @conditional_edges,
-          entry_point: @entry_point || @nodes.keys.first,
-          before_callbacks: @before_callbacks.dup,
-          after_callbacks: @after_callbacks.dup,
-          state_store: state_store
-        )
-      end
-
-      attr_reader :conditional_edges
-    end
-  end
-end

data/lib/phronomy/graph.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "graph/state"
-require_relative "graph/parallel_node"
-require_relative "graph/state_graph"
-require_relative "graph/compiled_graph"
-
-module Phronomy
-  module Graph
-    # Raised when a parallel branch exceeds the wall-clock limit set via +timeout:+.
-    class TimeoutError < Phronomy::Error; end
-  end
-end