phronomy 0.1.4 → 0.2.1

data/lib/phronomy/workflow_runner.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "state_machines"
+
+module Phronomy
+  # Execution engine for compiled workflows.
+  # Manages node execution, phase transitions, halt/resume, and wait states.
+  # Instantiated by Phronomy::Workflow and used internally.
+  #
+  # == Design principle
+  #
+  # State transitions are driven entirely by state_machines. The PhaseTracker
+  # holds a reference to the current WorkflowContext via +attr_accessor :context+,
+  # and guard lambdas evaluate +m.context+ (the WorkflowContext) rather than
+  # the PhaseTracker itself. This ensures that "what happens next" is always
+  # determined by the declared state machine topology, never by Phronomy internals.
+  #
+  # == Three transition categories registered in PhaseTracker
+  #
+  #   1. advance_<from>  — automatic, unconditional after-transitions
+  #                        fired when an action state's action completes
+  #                        (declared with +after :foo, to: :bar+)
+  #
+  #   2. route           — a single event that carries all guarded transitions
+  #                        (declared with +event :route, from: :foo, guard: ..., to: :bar+)
+  #                        Guards are evaluated in declaration order; first match wins.
+  #                        An unguarded fallback, if declared, is evaluated last.
+  #
+  #   3. <event_name>    — external events triggered by human input, originating
+  #                        from wait states
+  #                        (declared with +event :approve, from: :awaiting, to: :run+)
+  class WorkflowRunner
+    include Phronomy::Runnable
+
+    # Sentinel value for the terminal state of a workflow.
+    FINISH = :__end__
+
+    def initialize(state_class:, nodes:, after_transitions:, route_transitions:,
+      external_events:, entry_point:, wait_state_names: [],
+      before_callbacks: {}, after_callbacks: {}, state_store: nil)
+      @state_class = state_class
+      @nodes = nodes
+      @after_transitions = after_transitions  # { from => to }
+      @route_transitions = route_transitions  # { from => [{guard:, to:}, ...] }
+      @external_events = external_events    # { name => [{from:, to:, guard:}, ...] }
+      @entry_point = entry_point
+      @wait_state_names = wait_state_names
+      @before_callbacks = before_callbacks.dup
+      @after_callbacks = after_callbacks.dup
+      @state_store_override = state_store
+      @phase_machine_class = build_phase_machine_class
+    end
+
+    # Executes the workflow from the initial state.
+    # @param input [Hash] initial context field values
+    # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id: }
+    # @return [Object] final context (includes Phronomy::WorkflowContext)
+    def invoke(input, config: {})
+      caller_meta = {}
+      caller_meta[:user_id] = config[:user_id] if config[:user_id]
+      caller_meta[:session_id] = config[:session_id] if config[:session_id]
+
+      trace("graph.invoke", input: input.inspect, **caller_meta) do |_span|
+        thread_id = config[:thread_id] || SecureRandom.uuid
+        recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
+        state = @state_class.new(**input)
+        state.set_graph_metadata(thread_id: thread_id)
+        result = run_graph(state, recursion_limit: recursion_limit)
+        [result, nil]
+      end
+    end
+
+    # Generic resume. Equivalent to +send_event(state:, event: :resume, input:)+.
+    # @param state [Object] halted context
+    # @param input [Hash, nil] optional field updates to merge before resuming
+    # @return [Object] final context
+    def resume(state:, input: nil)
+      send_event(state: state, event: :resume, input: input)
+    end
+
+    # Fires a named event to advance a halted workflow.
+    #
+    # The special event +:resume+ selects the first external event registered
+    # for the current wait state and fires it.
+    #
+    # @param state [Object] halted context
+    # @param event [Symbol] named event or +:resume+ for generic resumption
+    # @param input [Hash, nil] optional field updates to merge before resuming
+    # @return [Object] final context
+    def send_event(state:, event:, input: nil)
+      state = state.merge(input) if input
+      event = event.to_sym
+      current_phase = state.phase
+
+      tracker = new_phase_machine(current_phase)
+      tracker.context = state
+
+      ev_to_fire = if event == :resume
+        # Find the first external event that can originate from the current wait state.
+        name, = @external_events.find { |_, ts| ts.any? { |t| t[:from] == current_phase } }
+        unless name
+          raise ArgumentError,
+            "No external event registered for wait state #{current_phase.inspect}"
+        end
+        name
+      else
+        unless @external_events.key?(event)
+          raise ArgumentError,
+            "Unknown event #{event.inspect}. Valid events: #{@external_events.keys.inspect}"
+        end
+        event
+      end
+
+      fire_event!(tracker, ev_to_fire, current_phase)
+
+      next_phase = tracker.phase.to_sym
+      next_node = (next_phase == :__end__) ? FINISH : next_phase
+      run_graph(state, from_node: next_node)
+    end
+
+    # Streaming execution. Yields { node: Symbol, state: Object } after each node completes.
+    # @param input [Hash]
+    # @param config [Hash]
+    # @yield [Hash]
+    # @return [Object] final context
+    def stream(input, config: {}, &block)
+      thread_id = config[:thread_id] || SecureRandom.uuid
+      recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
+      state = @state_class.new(**input)
+      state.set_graph_metadata(thread_id: thread_id)
+      run_graph(state, recursion_limit: recursion_limit, &block)
+    end
+
+    private
+
+    def state_store
+      @state_store_override || Phronomy.configuration.default_state_store
+    end
+
+    def run_graph(state, from_node: nil, recursion_limit: 25, &event_block)
+      current_node = from_node || @entry_point
+      tracker = new_phase_machine(current_node)
+      tracker.context = state
+      step = 0
+
+      while current_node && current_node != FINISH
+        if step >= recursion_limit
+          raise Phronomy::RecursionLimitError,
+            "Recursion limit (#{recursion_limit}) exceeded"
+        end
+
+        # Auto-halt at wait states: save context and return to caller.
+        if @wait_state_names.include?(current_node)
+          state.set_graph_metadata(thread_id: state.thread_id, phase: current_node)
+          state_store&.save(state)
+          return state
+        end
+
+        node_fn = @nodes[current_node]
+        raise ArgumentError, "Node #{current_node.inspect} is not defined" unless node_fn
+
+        result = node_fn.call(state)
+        state = case result
+        when Hash then state.merge(result)
+        when @state_class then result
+        when nil then state
+        else
+          raise ArgumentError,
+            "Node #{current_node} returned #{result.class}; " \
+            "expected Hash, #{@state_class}, or nil"
+        end
+
+        # Update tracker so guards see the freshest context.
+        tracker.context = state
+
+        event_block&.call({node: current_node, state: state})
+
+        # Delegate transition decision to state_machines.
+        if @after_transitions.key?(current_node)
+          fire_event!(tracker, :"advance_#{current_node}", current_node)
+        elsif @route_transitions.key?(current_node)
+          ev_name = @route_transitions[current_node][:event_name]
+          fire_event!(tracker, ev_name, current_node)
+        end
+        # Nodes with no declared outgoing transition are treated as terminal:
+        # next_phase == current_node triggers the FINISH assignment below.
+
+        next_phase = tracker.phase.to_sym
+        # When next_phase == current_node: no transition fired (terminal node) → end.
+        # When next_phase == :__end__ (== FINISH): route led to finish → exit loop.
+        current_node = (next_phase == current_node) ? FINISH : next_phase
+
+        step += 1
+      end
+
+      state.set_graph_metadata(thread_id: state.thread_id, phase: :__end__)
+      state_store&.save(state)
+      state
+    end
+
+    # Fires +event_name+ on +tracker+, raising a descriptive error if no
+    # transition matches. state_machines event methods return false when no
+    # transition can be taken (invalid state or all guards fail).
+    def fire_event!(tracker, event_name, from_node)
+      return if tracker.send(event_name)
+
+      raise ArgumentError,
+        "Transition from #{from_node.inspect} via event #{event_name.inspect} failed. " \
+        "Ensure at least one guard matches or add a fallback (no-guard) transition."
+    end
+
+    # Builds the PhaseTracker class backed by state_machines.
+    #
+    # Three event types are registered:
+    #   advance_<from>  — unconditional after-transitions
+    #   route           — all guarded routing transitions (one event, multiple transitions)
+    #   <external_name> — external events originating from wait states
+    #
+    # Guard lambdas bridge the PhaseTracker and WorkflowContext via +m.context+.
+    def build_phase_machine_class
+      entry = @entry_point
+      all_states = (@nodes.keys + @wait_state_names + [:__end__]).uniq
+      after_trans = @after_transitions   # { from => to }
+      route_trans = @route_transitions   # { from => [{guard:, to:}, ...] }
+      ext_events = @external_events     # { name => [{from:, to:, guard:}, ...] }
+
+      Class.new do
+        # Holds the current WorkflowContext so guards can read it.
+        attr_accessor :context
+
+        state_machine :phase, initial: entry do
+          all_states.each { |s| state s }
+
+          # 1. After-transitions: unconditional, fire on action completion.
+          after_trans.each do |from, to|
+            event :"advance_#{from}" do
+              transition from => to
+            end
+          end
+
+          # 2. Route events: one named event per from-state (name may vary).
+          #    Declaration order is preserved; guards first, unguarded fallback last.
+          route_trans.each do |from, routing|
+            event routing[:event_name] do
+              routing[:entries].each do |t|
+                if t[:guard]
+                  guard_proc = t[:guard]
+                  transition from => t[:to], :if => ->(m) { guard_proc.call(m.context) }
+                else
+                  transition from => t[:to]
+                end
+              end
+            end
+          end
+
+          # 3. External events: human-in-the-loop triggers from wait states.
+          ext_events.each do |ev_name, transitions|
+            event ev_name do
+              transitions.each do |t|
+                if t[:guard]
+                  guard_proc = t[:guard]
+                  transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
+                else
+                  transition t[:from] => t[:to]
+                end
+              end
+            end
+          end
+        end
+      end
+    rescue => e
+      raise ArgumentError, "Failed to build phase machine: #{e.message}"
+    end
+
+    # Creates a PhaseTracker instance initialized to +from_node+.
+    def new_phase_machine(from_node)
+      machine = @phase_machine_class.new
+      # Override the initial state set by state_machine's initializer so we can
+      # resume from an arbitrary node (e.g. after a wait state).
+      machine.instance_variable_set(:@phase, from_node.to_s)
+      machine
+    end
+  end
+end

data/lib/phronomy.rb

@@ -35,46 +35,42 @@ module Phronomy
     end
   end
 
-  # Namespace for graph-related classes (StateGraph, State, ParallelNode, …).
-  # Also serves as the registry for State classes that may be serialized to
-  # external stores (Redis, DB). Call +register_state_class+ at application
-  # startup so that only known classes can be deserialized.
-  module Graph
-    @state_class_registry = nil
-    @registry_mutex = Mutex.new
-
-    class << self
-      # Register one or more State classes that are allowed to be deserialized
-      # by StateStore backends. When at least one class is registered, only
-      # registered classes will be accepted by +StateStore::Base#safe_state_class+.
-      #
-      # Call this once at application startup (e.g. in a Rails initializer).
-      #
-      # @param classes [Array<Class>] classes including Phronomy::Graph::State
-      # @example
-      #   Phronomy::Graph.register_state_class(MyWorkflowState, OtherState)
-      def register_state_class(*classes)
-        @registry_mutex.synchronize do
-          @state_class_registry ||= {}
-          classes.each do |klass|
-            raise ArgumentError, "#{klass.inspect} is not a Class" unless klass.is_a?(Class)
-            @state_class_registry[klass.name] = klass
-          end
+  # Registry for WorkflowContext classes that may be serialized to external stores
+  # (Redis, DB). Call +register_workflow_context+ at application startup so that
+  # only known classes can be deserialized.
+  @workflow_context_registry = nil
+  @registry_mutex = Mutex.new
+
+  class << self
+    # Register one or more WorkflowContext classes that are allowed to be
+    # deserialized by StateStore backends. When at least one class is registered,
+    # only registered classes will be accepted by
+    # +StateStore::Base#safe_state_class+.
+    #
+    # Call this once at application startup (e.g. in a Rails initializer).
+    #
+    # @param classes [Array<Class>] classes including Phronomy::WorkflowContext
+    # @example
+    #   Phronomy.register_workflow_context(ScanContext, OtherContext)
+    def register_workflow_context(*classes)
+      @registry_mutex.synchronize do
+        @workflow_context_registry ||= {}
+        classes.each do |klass|
+          raise ArgumentError, "#{klass.inspect} is not a Class" unless klass.is_a?(Class)
+          @workflow_context_registry[klass.name] = klass
         end
       end
+    end
 
-      # Returns the current registry Hash, or nil when no class has been registered.
-      # @return [Hash{String => Class}, nil]
-      attr_reader :state_class_registry
+    # Returns the current registry Hash, or nil when no class has been registered.
+    # @return [Hash{String => Class}, nil]
+    attr_reader :workflow_context_registry
 
-      # Clears the registry. Primarily used in tests.
-      def reset_state_class_registry!
-        @registry_mutex.synchronize { @state_class_registry = nil }
-      end
+    # Clears the registry. Primarily used in tests.
+    def reset_workflow_context_registry!
+      @registry_mutex.synchronize { @workflow_context_registry = nil }
     end
-  end
 
-  class << self
     def configuration
       @configuration ||= Configuration.new
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.1
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -38,9 +38,23 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.6'
-description: Phronomy provides Agent, Graph, Memory, Tool, Guardrail, RAG, and Multi-agent
-  capabilities for building AI agents in Ruby and Rails. Powered by RubyLLM for LLM
-  abstraction.
+- !ruby/object:Gem::Dependency
+  name: state_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: Phronomy provides Agent, Workflow, Memory, Tool, Guardrail, RAG, and
+  Multi-agent capabilities for building AI agents in Ruby and Rails. Powered by RubyLLM
+  for LLM abstraction.
 email:
 - raizo.tcs@gmail.com
 executables: []
@@ -48,6 +62,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
+- CHANGELOG.md
 - README.md
 - Rakefile
 - docs/trustworthy_ai_enhancements.md
@@ -60,6 +75,7 @@ files:
 - lib/phronomy/active_record/checkpoint.rb
 - lib/phronomy/active_record/extensions.rb
 - lib/phronomy/active_record/message.rb
+- lib/phronomy/actor.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_completion_context.rb
@@ -91,11 +107,6 @@ files:
 - lib/phronomy/eval/scorer/exact_match.rb
 - lib/phronomy/eval/scorer/includes_scorer.rb
 - lib/phronomy/eval/scorer/llm_judge.rb
-- lib/phronomy/graph.rb
-- lib/phronomy/graph/compiled_graph.rb
-- lib/phronomy/graph/parallel_node.rb
-- lib/phronomy/graph/state.rb
-- lib/phronomy/graph/state_graph.rb
 - lib/phronomy/guardrail.rb
 - lib/phronomy/guardrail/base.rb
 - lib/phronomy/guardrail/builtin.rb
@@ -146,8 +157,10 @@ files:
 - lib/phronomy/state_store/encryptor.rb
 - lib/phronomy/state_store/encryptor/active_support.rb
 - lib/phronomy/state_store/encryptor/base.rb
+- lib/phronomy/state_store/file.rb
 - lib/phronomy/state_store/in_memory.rb
 - lib/phronomy/state_store/redis.rb
+- lib/phronomy/thread_actor_registry.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
 - lib/phronomy/tool/agent_tool.rb
@@ -165,6 +178,9 @@ files:
 - lib/phronomy/vector_store/pgvector.rb
 - lib/phronomy/vector_store/redis_search.rb
 - lib/phronomy/version.rb
+- lib/phronomy/workflow.rb
+- lib/phronomy/workflow_context.rb
+- lib/phronomy/workflow_runner.rb
 - sig/phronomy.rbs
 - vendor/bundle/ruby/3.2.0/bin/erb
 - vendor/bundle/ruby/3.2.0/bin/htmldiff

data/lib/phronomy/graph/compiled_graph.rb

@@ -1,191 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Phronomy
-  module Graph
-    # Executable graph produced by StateGraph#compile.
-    # Includes Runnable so it can be embedded in a larger pipeline.
-    class CompiledGraph
-      include Phronomy::Runnable
-
-      def initialize(state_class:, nodes:, edges:, conditional_edges:, entry_point:,
-        before_callbacks: {}, after_callbacks: {}, state_store: nil)
-        @state_class = state_class
-        @nodes = nodes
-        @edges = edges
-        @conditional_edges = conditional_edges
-        @entry_point = entry_point
-        @before_callbacks = before_callbacks
-        @after_callbacks = after_callbacks
-        @state_store_override = state_store
-      end
-
-      # Registers a callback to run before the given node executes.
-      # Return :halt from the block to pause execution; any other value continues.
-      # @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.
-      # @param node [Symbol]
-      # @yield [state] the state after the node ran
-      # @return [self]
-      def interrupt_after(node, &block)
-        @after_callbacks[node] = block
-        self
-      end
-
-      # Executes the graph from the entry point.
-      # Automatically assigns a thread_id if not supplied via config.
-      # @param input [Hash] initial state field values
-      # @param config [Hash] { thread_id: String, recursion_limit: Integer,
-      #   user_id: String (optional), session_id: String (optional) }
-      # @return [Object] final state (includes Phronomy::Graph::State)
-      def invoke(input, config: {})
-        caller_meta = {}
-        caller_meta[:user_id] = config[:user_id] if config[:user_id]
-        caller_meta[:session_id] = config[:session_id] if config[:session_id]
-
-        trace("graph.invoke", input: input.inspect, **caller_meta) do |_span|
-          thread_id = config[:thread_id] || SecureRandom.uuid
-          recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
-          state = @state_class.new(**input)
-          state.set_graph_metadata(thread_id: thread_id, current_nodes: [], halted_before: false)
-          result = execute_graph(state, recursion_limit: recursion_limit)
-          [result, nil]
-        end
-      end
-
-      # Resumes a halted graph from the state returned by a previous invoke/resume.
-      # @param state [Object] state object (includes Phronomy::Graph::State) with current_nodes set
-      # @param input [Hash, nil] optional field updates to merge before resuming
-      # @return [Object] final state
-      def resume(state:, input: nil)
-        state = state.merge(input) if input
-        from_nodes = state.current_nodes
-        raise ArgumentError, "State has no pending nodes to resume from" if from_nodes.nil? || from_nodes.empty?
-
-        execute_graph(state, from_node: from_nodes.first,
-          skip_first_before: state.halted_before)
-      end
-
-      # Streaming execution. Yields { node: Symbol, state: State } after each node completes.
-      # @param input [Hash]
-      # @param config [Hash]
-      # @yield [Hash] { node: Symbol, state: State }
-      # @return [Object] final state
-      def stream(input, config: {}, &block)
-        thread_id = config[:thread_id] || SecureRandom.uuid
-        recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
-        state = @state_class.new(**input)
-        state.set_graph_metadata(thread_id: thread_id, current_nodes: [], halted_before: false)
-        execute_graph(state, recursion_limit: recursion_limit, &block)
-      end
-
-      private
-
-      def state_store
-        @state_store_override || Phronomy.configuration.default_state_store
-      end
-
-      def execute_graph(state, from_node: nil, recursion_limit: 25,
-        skip_first_before: false, &event_block)
-        current_node = from_node || @entry_point
-        step = 0
-        first_step = true
-
-        while current_node && current_node != StateGraph::FINISH
-          if step >= recursion_limit
-            raise Phronomy::RecursionLimitError,
-              "Recursion limit (#{recursion_limit}) exceeded"
-          end
-
-          # interrupt_before callback
-          unless skip_first_before && first_step
-            if (cb = @before_callbacks[current_node])
-              if cb.call(state) == :halt
-                state.set_graph_metadata(
-                  thread_id: state.thread_id,
-                  current_nodes: [current_node],
-                  halted_before: true
-                )
-                state_store&.save(state)
-                return state
-              end
-            end
-          end
-          first_step = false
-
-          node_fn = @nodes[current_node]
-          raise ArgumentError, "Node #{current_node} is not defined" unless node_fn
-
-          result = node_fn.call(state)
-          state = case result
-          when Hash then state.merge(result)
-          when @state_class then result
-          when nil then state
-          else
-            raise ArgumentError,
-              "Node #{current_node} returned #{result.class}; expected Hash, #{@state_class}, or nil"
-          end
-
-          event_block&.call({node: current_node, state: state})
-
-          # interrupt_after callback
-          if (cb = @after_callbacks[current_node])
-            next_n = next_node(current_node, state)
-            if cb.call(state) == :halt
-              state.set_graph_metadata(
-                thread_id: state.thread_id,
-                current_nodes: [next_n].compact,
-                halted_before: false
-              )
-              state_store&.save(state)
-              return state
-            end
-            current_node = next_n
-          else
-            current_node = next_node(current_node, state)
-          end
-
-          step += 1
-        end
-
-        state.set_graph_metadata(
-          thread_id: state.thread_id,
-          current_nodes: [],
-          halted_before: false
-        )
-        state_store&.save(state)
-        state
-      end
-
-      def next_node(current, state)
-        if (cond = @conditional_edges[current])
-          result = cond[:condition].call(state)
-          if cond[:mapping]
-            unless cond[:mapping].key?(result)
-              raise ArgumentError,
-                "Conditional edge from #{current.inspect} returned #{result.inspect}, " \
-                "which is not present in the mapping (#{cond[:mapping].keys.inspect})"
-            end
-            return cond[:mapping][result]
-          end
-          return result
-        end
-
-        edges = @edges[current]
-        return nil unless edges&.any?
-
-        matched = edges.find { |edge| edge[:condition].nil? || edge[:condition].call(state) }
-        matched&.fetch(:to)
-      end
-    end
-  end
-end