phronomy 0.5.4 → 0.6.0

data/lib/phronomy/workflow_context.rb

@@ -49,7 +49,7 @@ module Phronomy
     # Encoding:
     #   :__end__           — workflow completed (or not yet started)
     #   :awaiting_<name>   — halted at a wait_state(:awaiting_<name>) declaration
-    #   :<node>            — resuming at <node> (workflow paused before its execution)
+    #   :<state>           — resuming at <state> (workflow paused before its execution)
     # @return [Symbol]
     def phase
       @phase || :__end__

data/lib/phronomy/workflow_runner.rb

@@ -5,7 +5,7 @@ require "state_machines"
 
 module Phronomy
   # Execution engine for compiled workflows.
-  # Manages node execution, phase transitions, halt/resume, and wait states.
+  # Manages state entry/exit action execution, phase transitions, halt/resume, and wait states.
   # Instantiated by Phronomy::Workflow and used internally.
   #
   # == Design principle
@@ -16,39 +16,41 @@ module Phronomy
   # 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
+  # Entry and exit actions are registered as state_machines +after_transition to:+
+  # and +before_transition from:+ callbacks respectively. The WorkflowContext is
+  # mutable; actions receive it and modify fields in place.
   #
-  #   1. advance_<from>  — automatic, unconditional after-transitions
-  #                        fired when an action state's action completes
-  #                        (declared with +after :foo, to: :bar+)
+  # The sole exception is the initial state: state_machines does not fire transition
+  # callbacks on initialization, so the entry action for the entry point is invoked
+  # directly by WorkflowRunner before the main execution loop begins.
   #
-  #   2. route           — a single event that carries all guarded transitions
-  #                        (declared with +event :route, from: :foo, guard: ..., to: :bar+)
+  # == Two transition categories registered in PhaseTracker
+  #
+  #   1. state_completed  — all auto-fire transitions (with or without guards).
+  #                        Fired when an action state's action completes.
   #                        Guards are evaluated in declaration order; first match wins.
-  #                        An unguarded fallback, if declared, is evaluated last.
+  #                        (declared with +transition from: :foo, to: :bar+ or
+  #                         +transition from: :foo, guard: ..., to: :bar+)
   #
-  #   3. <event_name>    — external events triggered by human input, originating
+  #   2. <event_name>    — external events triggered by human input, originating
   #                        from wait states
-  #                        (declared with +event :approve, from: :awaiting, to: :run+)
+  #                        (declared with +transition from: :awaiting, on: :approve, 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: {})
+    def initialize(state_class:, entry_actions:, declared_states:, auto_transitions:, external_events:, entry_point:, exit_actions: {}, wait_state_names: [])
       @state_class = state_class
-      @nodes = nodes
-      @after_transitions = after_transitions  # { from => to }
-      @route_transitions = route_transitions  # { from => [{guard:, to:}, ...] }
+      @entry_actions = entry_actions   # { state_name => [callable, ...] }
+      @declared_states = declared_states
+      # Lookup set: states with at least one auto-fire transition declared.
+      @auto_state_set = auto_transitions.each_with_object({}) { |t, h| h[t[:from]] = true }
       @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
-      @phase_machine_class = build_phase_machine_class
+      @phase_machine_class = build_phase_machine_class(auto_transitions, exit_actions)
     end
 
     # Executes the workflow from the initial state.
@@ -60,12 +62,16 @@ module Phronomy
       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|
+      trace("workflow.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 = if Phronomy.configuration.event_loop
+          run_via_event_loop(state, recursion_limit: recursion_limit)
+        else
+          run_workflow(state, recursion_limit: recursion_limit)
+        end
         [result, nil]
       end
     end
@@ -92,9 +98,6 @@ module Phronomy
       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 } }
@@ -111,14 +114,16 @@ module Phronomy
         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)
+      if Phronomy.configuration.event_loop
+        run_via_event_loop(state,
+          recursion_limit: Phronomy.configuration.recursion_limit,
+          resume_event: ev_to_fire, resume_phase: current_phase)
+      else
+        run_workflow(state, resume_event: ev_to_fire, resume_phase: current_phase)
+      end
     end
 
-    # Streaming execution. Yields { node: Symbol, state: Object } after each node completes.
+    # Streaming execution. Yields { state: Symbol, context: Object } after each state action completes.
     # @param input [Hash]
     # @param config [Hash]
     # @yield [Hash]
@@ -128,145 +133,173 @@ module Phronomy
       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)
+      run_workflow(state, recursion_limit: recursion_limit, &block)
     end
 
     private
 
-    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
-      # Event queue: decouple node execution from transition firing.
-      # Events are enqueued after a node completes and processed at the top
+    # Builds an FSMSession for the given context. Used in EventLoop mode.
+    def build_session_for(context:, recursion_limit:, resume_event: nil, resume_phase: nil)
+      Phronomy::FSMSession.new(
+        id: context.thread_id,
+        context: context,
+        entry_point: @entry_point,
+        entry_actions: @entry_actions,
+        auto_state_set: @auto_state_set,
+        declared_states: @declared_states,
+        wait_state_names: @wait_state_names,
+        external_events: @external_events,
+        phase_machine_class: @phase_machine_class,
+        recursion_limit: recursion_limit,
+        resume_event: resume_event,
+        resume_phase: resume_phase
+      )
+    end
+
+    # Executes the workflow via the singleton EventLoop.
+    # Blocks the calling thread on a completion queue until the workflow
+    # finishes, halts at a wait state, or raises an error.
+    def run_via_event_loop(context, recursion_limit:, resume_event: nil, resume_phase: nil)
+      session = build_session_for(
+        context: context, recursion_limit: recursion_limit,
+        resume_event: resume_event, resume_phase: resume_phase
+      )
+      completion_queue = Phronomy::EventLoop.instance.register(session)
+      result = completion_queue.pop
+      raise result if result.is_a?(Exception)
+      result
+    end
+
+    def run_workflow(ctx, resume_event: nil, resume_phase: nil, recursion_limit: 25, &event_block)
+      if resume_event
+        # -- Resume from a wait state -------------------------------------------
+        # Fire the external event on a tracker positioned at the wait state.
+        # state_machines will invoke before_transition (exit) and after_transition
+        # (entry) callbacks as part of the transition, so both actions fire here.
+        current_state = resume_phase
+        tracker = new_phase_machine(current_state)
+        tracker.context = ctx
+        fire_event!(tracker, resume_event, current_state)
+        next_phase = tracker.phase.to_sym
+        current_state = (next_phase == current_state) ? FINISH : next_phase
+      else
+        # -- Fresh start --------------------------------------------------------
+        current_state = @entry_point
+        tracker = new_phase_machine(current_state)
+        tracker.context = ctx
+        # state_machines only fires after_transition callbacks on transitions.
+        # The entry point has no prior transition, so we invoke its entry actions directly.
+        @entry_actions[current_state]&.each { |c| c.call(ctx) }
+      end
+
+      # Event queue: decouple action execution from transition firing.
+      # Events are enqueued after visiting a state and processed at the top
       # of the next iteration so that guards always see the freshest context.
       event_queue = []
       step = 0
 
       loop do
-        break if current_node == FINISH
+        break if current_state == FINISH
 
         # -- Process next pending event -----------------------------------------
         # Dequeue one event and fire it against the state machine. Guards are
-        # evaluated here (at fire time) so they see the context written by the
-        # node that enqueued the event.
+        # evaluated here (at fire time). Entry/exit callbacks fire inside fire_event!.
         if (event = event_queue.shift)
           if step >= recursion_limit
             raise Phronomy::RecursionLimitError,
               "Recursion limit (#{recursion_limit}) exceeded"
           end
 
-          fire_event!(tracker, event, current_node)
+          fire_event!(tracker, event, current_state)
           next_phase = tracker.phase.to_sym
-          # When next_phase == current_node no transition matched → terminal node.
-          current_node = (next_phase == current_node) ? FINISH : next_phase
+          # When next_phase == current_state no transition matched → terminal state.
+          current_state = (next_phase == current_state) ? FINISH : next_phase
           step += 1
           next
         end
 
         # -- Queue empty: check for halt -----------------------------------------
         # Auto-halt at wait states: persist phase in context and return to caller.
-        # The caller resumes via send_event, which starts a fresh run_graph call.
-        if @wait_state_names.include?(current_node)
-          state.set_graph_metadata(thread_id: state.thread_id, phase: current_node)
-          return state
+        # The caller resumes via send_event.
+        if @wait_state_names.include?(current_state)
+          ctx.set_graph_metadata(thread_id: ctx.thread_id, phase: current_state)
+          return ctx
         end
 
-        # -- Execute node action ------------------------------------------------
-        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"
+        # -- Validate state is known --------------------------------------------
+        unless @declared_states.include?(current_state)
+          raise ArgumentError, "State #{current_state.inspect} is not defined"
         end
 
-        # Update tracker so guards see the freshest context when the event fires.
-        tracker.context = state
+        # -- Emit stream event and enqueue transition ---------------------------
+        # Entry action for current_state has already been invoked (either by the
+        # initial manual call above, or by the after_transition callback fired
+        # inside fire_event! on the previous iteration).
+        event_block&.call({state: current_state, context: ctx})
 
-        event_block&.call({node: current_node, state: state})
-
-        # -- Enqueue transition event -------------------------------------------
-        # node_completed: generic event for all after-transitions (unconditional).
-        # route event:    user-named event carrying guarded conditional branches.
-        # No enqueue:     terminal node — next iteration exits via FINISH check.
-        if @after_transitions.key?(current_node)
-          event_queue << :node_completed
-        elsif @route_transitions.key?(current_node)
-          event_queue << @route_transitions[current_node][:event_name]
+        # state_completed: unified event for all auto-fire transitions.
+        # No enqueue:      terminal state — next iteration exits via FINISH check.
+        if @auto_state_set.key?(current_state)
+          event_queue << :state_completed
         else
-          current_node = FINISH
+          current_state = FINISH
         end
       end
 
-      state.set_graph_metadata(thread_id: state.thread_id, phase: :__end__)
-      state
+      ctx.set_graph_metadata(thread_id: ctx.thread_id, phase: :__end__)
+      ctx
     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)
+    def fire_event!(tracker, event_name, from_state)
       return if tracker.send(event_name)
 
       raise ArgumentError,
-        "Transition from #{from_node.inspect} via event #{event_name.inspect} failed. " \
+        "Transition from #{from_state.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
+    # Four event/callback types are registered:
+    #   state_completed       — all auto-fire transitions (guarded and unguarded)
+    #   <external_name>       — external events originating from wait states
+    #   after_transition to   — entry callbacks (invoked when entering a state)
+    #   before_transition from — exit callbacks (invoked when leaving a state)
     #
     # Guard lambdas bridge the PhaseTracker and WorkflowContext via +m.context+.
-    def build_phase_machine_class
+    def build_phase_machine_class(auto_transitions, exit_actions)
       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:}, ...] }
+      all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
+      auto_trans = auto_transitions  # Array of { from:, to:, guard: }
+      ext_events = @external_events
+      entry_acts = @entry_actions
+      exit_acts = exit_actions
 
       Class.new do
-        # Holds the current WorkflowContext so guards can read it.
+        # Holds the current WorkflowContext so guards and callbacks can read it.
         attr_accessor :context
 
         state_machine :phase, initial: entry do
           all_states.each { |s| state s }
 
-          # 1. After-transitions: one generic :node_completed event covers all
-          #    unconditional transitions. This keeps event names independent of
-          #    source state names and matches standard state machine semantics.
-          event :node_completed do
-            after_trans.each do |from, to|
-              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
+          # Auto-fire transitions: all auto transitions unified under :state_completed.
+          # Includes unguarded (unconditional) and guarded (conditional) transitions.
+          # Declaration order is preserved; guards are evaluated before unguarded fallbacks.
+          event :state_completed do
+            auto_trans.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
 
-          # 3. External events: human-in-the-loop triggers from wait states.
+          # 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|
@@ -279,18 +312,40 @@ module Phronomy
               end
             end
           end
+
+          # Entry callbacks: fire after_transition into each state.
+          #    Each callable is registered as a separate callback; state_machines
+          #    accumulates them and fires in declaration order.
+          entry_acts.each do |state_name, callables|
+            callables.each do |callable|
+              after_transition to: state_name do |machine|
+                callable.call(machine.context)
+              end
+            end
+          end
+
+          # Exit callbacks: fire before_transition out of each state.
+          #    Each callable is registered as a separate callback; state_machines
+          #    accumulates them and fires in declaration order.
+          exit_acts.each do |state_name, callables|
+            callables.each do |callable|
+              before_transition from: state_name do |machine|
+                callable.call(machine.context)
+              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)
+    # Creates a PhaseTracker instance initialized to +from_state+.
+    def new_phase_machine(from_state)
       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)
+      # resume from an arbitrary state (e.g. after a wait state).
+      machine.instance_variable_set(:@phase, from_state.to_s)
       machine
     end
   end

data/lib/phronomy.rb

@@ -8,6 +8,10 @@ loader = Zeitwerk::Loader.for_gem
 # Teach Zeitwerk that "llm" maps to "LLM" so that file names such as
 # ruby_llm_embeddings.rb resolve to RubyLLMEmbeddings (not RubyLlmEmbeddings).
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
+# FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
+loader.inflector.inflect("fsm_session" => "FSMSession")
+# AgentFSM: Zeitwerk would infer "Fsm" — override to "FSM".
+loader.inflector.inflect("fsm" => "FSM")
 loader.setup
 
 require_relative "phronomy/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-20 00:00:00.000000000 Z
+date: 2026-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -73,8 +73,10 @@ files:
 - lib/phronomy/agent/concerns/guardrailable.rb
 - lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/concerns/suspendable.rb
+- lib/phronomy/agent/fsm.rb
 - lib/phronomy/agent/handoff.rb
 - lib/phronomy/agent/orchestrator.rb
+- lib/phronomy/agent/parallel_tool_chat.rb
 - lib/phronomy/agent/react_agent.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
@@ -83,7 +85,6 @@ files:
 - lib/phronomy/configuration.rb
 - lib/phronomy/context.rb
 - lib/phronomy/context/assembler.rb
-- lib/phronomy/context/builder.rb
 - lib/phronomy/context/compaction_context.rb
 - lib/phronomy/context/context_version_cache.rb
 - lib/phronomy/context/token_budget.rb
@@ -105,12 +106,12 @@ files:
 - lib/phronomy/eval/scorer/exact_match.rb
 - lib/phronomy/eval/scorer/includes_scorer.rb
 - lib/phronomy/eval/scorer/llm_judge.rb
+- lib/phronomy/event.rb
+- lib/phronomy/event_loop.rb
+- lib/phronomy/fsm_session.rb
 - lib/phronomy/generator_verifier.rb
 - lib/phronomy/guardrail.rb
 - lib/phronomy/guardrail/base.rb
-- lib/phronomy/guardrail/builtin.rb
-- lib/phronomy/guardrail/builtin/pii_pattern_detector.rb
-- lib/phronomy/guardrail/builtin/prompt_injection_detector.rb
 - lib/phronomy/guardrail/input_guardrail.rb
 - lib/phronomy/guardrail/output_guardrail.rb
 - lib/phronomy/knowledge_source.rb

data/lib/phronomy/context/builder.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Context
-    # Assembles ordered context sections (system prompt, knowledge, conversation
-    # history) within a given token budget.
-    #
-    # Usage:
-    #   builder = Phronomy::Context::Builder.new(budget: budget)
-    #   builder.add_system(instructions_text)
-    #   builder.add_knowledge(knowledge_text)
-    #   builder.add_messages(messages)
-    #   messages_to_send = builder.build
-    #
-    # Sections are added in priority order. When the budget is exceeded the
-    # lower-priority tail of each section is truncated.
-    class Builder
-      # @param budget [Phronomy::Context::TokenBudget]
-      def initialize(budget:)
-        @budget = budget
-        @system = nil
-        @knowledge = []
-        @messages = []
-      end
-
-      # Set the system instructions text (highest priority).
-      # @param text [String]
-      def add_system(text)
-        @system = text.to_s
-        self
-      end
-
-      # Append knowledge/RAG text (medium priority).
-      # @param text [String]
-      def add_knowledge(text)
-        @knowledge << text.to_s
-        self
-      end
-
-      # Set conversation messages (lowest priority — oldest are dropped first).
-      # @param messages [Array] list of message-like objects with #role and #content
-      def add_messages(messages)
-        @messages = Array(messages)
-        self
-      end
-
-      # Assemble the context respecting the token budget.
-      #
-      # Returns a hash with:
-      #   :system   [String, nil] system prompt (instructions + knowledge)
-      #   :messages [Array]       conversation messages that fit within the budget
-      #
-      # @return [Hash]
-      def build
-        used = 0
-
-        # System prompt is always included (budget enforcement is informational only).
-        system_text = [@system, *@knowledge].compact.join("\n\n")
-        used += TokenEstimator.estimate(system_text)
-
-        # Conversation messages — keep as many recent messages as fit.
-        remaining = @budget.available(used: used)
-        kept = fit_messages_to_budget(@messages, remaining)
-
-        {
-          system: system_text.empty? ? nil : system_text,
-          messages: kept
-        }
-      end
-
-      private
-
-      # Greedily accumulate messages from newest to oldest, stop when budget runs out.
-      def fit_messages_to_budget(messages, token_limit)
-        return messages if token_limit <= 0 && messages.empty?
-
-        accumulated = 0
-        result = []
-
-        messages.reverse_each do |msg|
-          tokens = TokenEstimator.estimate(msg.content.to_s)
-          break if accumulated + tokens > token_limit
-
-          accumulated += tokens
-          result.unshift(msg)
-        end
-
-        result
-      end
-    end
-  end
-end