phronomy 0.1.4 → 0.2.0

data/lib/phronomy/workflow_runner.rb

@@ -0,0 +1,262 @@
+# 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.
+  #
+  # Wait states (registered via wait_states:) are virtual nodes
+  # that automatically halt execution when reached. They can be resumed with
+  # either #resume (generic) or #send_event (event-typed).
+  #
+  # Internally, a state_machines-based PhaseTracker class is generated at
+  # initialization time. The tracker validates phase transitions during
+  # execution; invalid transitions are logged as warnings without halting.
+  class WorkflowRunner
+    include Phronomy::Runnable
+
+    # Sentinel value for the terminal state of a workflow.
+    FINISH = :__end__
+
+    def initialize(state_class:, nodes:, edges:, conditional_edges:, entry_point:,
+      before_callbacks: {}, after_callbacks: {}, wait_states: {}, state_store: nil)
+      @state_class = state_class
+      @nodes = nodes
+      @edges = edges
+      @conditional_edges = conditional_edges
+      @entry_point = entry_point
+      @before_callbacks = before_callbacks.dup
+      @after_callbacks = after_callbacks.dup
+      # { wait_state_name => { resume_event: Symbol, resume_to: Symbol } }
+      @wait_states = wait_states.dup
+      @state_store_override = state_store
+      @phase_machine_class = build_phase_machine_class
+    end
+
+    # Executes the workflow from the entry point.
+    # @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. Routes based on the current phase encoding.
+    # 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+ is accepted for all halt types:
+    # - Named wait state → resumes at +resume_to+ node
+    #
+    # Any other event name must match the +resume_event:+ declared in
+    # the wait_states configuration.
+    #
+    # @param state [Object] halted context
+    # @param event [Symbol] +:resume+ for generic resumption, or a named event
+    # @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
+
+      if event == :resume
+        # Named wait state: use resume_to
+        if @wait_states.key?(current_phase)
+          return run_graph(state, from_node: @wait_states[current_phase][:resume_to])
+        end
+        raise ArgumentError, "State has no wait state registered for phase #{current_phase.inspect}"
+      end
+
+      # Named event lookup
+      _, wait_cfg = @wait_states.find { |_, c| c[:resume_event] == event }
+      unless wait_cfg
+        valid = @wait_states.values.filter_map { |c| c[:resume_event] }.uniq
+        raise ArgumentError, "Unknown event #{event.inspect}. Valid events: #{valid.inspect}"
+      end
+      run_graph(state, from_node: wait_cfg[:resume_to])
+    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)
+      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.
+        if @wait_states.key?(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} 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})
+
+        next_n = resolve_next_node(current_node, state)
+        advance_phase(tracker, current_node, next_n || FINISH)
+        current_node = next_n
+
+        step += 1
+      end
+
+      state.set_graph_metadata(thread_id: state.thread_id, phase: :__end__)
+      state_store&.save(state)
+      state
+    end
+
+    def resolve_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
+
+    # Builds a state_machines-based PhaseTracker class encoding the workflow topology.
+    # Returns nil if the build fails (execution continues without phase validation).
+    def build_phase_machine_class
+      entry = @entry_point
+      nodes = @nodes.keys
+      ws_names = @wait_states.keys
+
+      # Collect all valid (from, to) pairs; use a Hash to deduplicate.
+      trans = {}
+
+      @edges.each do |from, edge_list|
+        edge_list.each do |edge|
+          to = (edge[:to] == FINISH) ? :__end__ : edge[:to]
+          trans[[from, to]] = true
+        end
+      end
+
+      @conditional_edges.each do |from, cfg|
+        targets = cfg[:mapping] ? cfg[:mapping].values : (nodes + ws_names + [:__end__])
+        targets.each do |to|
+          t = (to == FINISH) ? :__end__ : to
+          trans[[from, t]] = true
+        end
+      end
+
+      # Any node can be terminal (no outgoing edge = implicit advance to :__end__).
+      nodes.each { |n| trans[[n, :__end__]] = true }
+
+      all_states = (nodes + ws_names + [:__end__]).uniq
+      trans_pairs = trans.keys
+
+      Class.new do
+        state_machine :phase, initial: entry do
+          all_states.each { |s| state s }
+          trans_pairs.each do |from, to|
+            event :"advance_#{from}_to_#{to}" do
+              transition from => to
+            end
+          end
+        end
+      end
+    rescue => e
+      warn "[Phronomy] Could not build phase machine: #{e.message}"
+      nil
+    end
+
+    # Creates a PhaseTracker instance initialised to +from_node+.
+    def new_phase_machine(from_node)
+      return nil unless @phase_machine_class && from_node
+
+      machine = @phase_machine_class.new
+      machine.instance_variable_set(:@phase, from_node.to_s)
+      machine
+    rescue => e
+      warn "[Phronomy] Phase machine init failed: #{e.message}"
+      nil
+    end
+
+    # Fires a transition event on the tracker from +from+ to +to+.
+    # Logs a warning if the transition is not declared; does not raise.
+    def advance_phase(tracker, from, to)
+      return unless tracker && from
+
+      to_sym = case to
+      when nil, FINISH then :__end__
+      else to
+      end
+      event_name = :"advance_#{from}_to_#{to_sym}"
+      unless tracker.fire_events(event_name)
+        warn "[Phronomy] Unexpected phase transition #{from.inspect} → #{to_sym.inspect}"
+      end
+    rescue => e
+      warn "[Phronomy] Phase tracker error (#{from}→#{to}): #{e.message}"
+    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.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-14 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
@@ -148,6 +159,7 @@ files:
 - lib/phronomy/state_store/encryptor/base.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 +177,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