phronomy 0.5.3 → 0.6.0

data/lib/phronomy/configuration.rb

@@ -28,6 +28,11 @@ module Phronomy
     # Recursion limit for graph execution (default: 25)
     attr_accessor :recursion_limit
 
+    # When true, workflow execution is driven by EventLoop instead of a
+    # synchronous loop in the calling thread. Defaults to false (sync mode).
+    # @see Phronomy::EventLoop
+    attr_accessor :event_loop
+
     # When true (default), user input and LLM output are recorded in trace spans.
     # Set to false in privacy-sensitive environments to prevent PII from reaching
     # the tracing backend (OTel, Langfuse, etc.).
@@ -37,6 +42,7 @@ module Phronomy
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new
       @trace_pii = true
+      @event_loop = false
     end
   end
 end

data/lib/phronomy/context.rb

@@ -7,7 +7,6 @@ module Phronomy
   # Sub-modules are auto-loaded by Zeitwerk:
   #   Phronomy::Context::TokenEstimator
   #   Phronomy::Context::TokenBudget
-  #   Phronomy::Context::Builder
   module Context
   end
 end

data/lib/phronomy/event.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Immutable event struct used for inter-FSM communication via EventLoop.
+  #
+  # @param type      [Symbol]  event identifier (:start, :state_completed,
+  #                            :finished, :halted, :error, or any user-defined name)
+  # @param target_id [String]  FSMSession identifier — matches WorkflowContext#thread_id
+  # @param payload   [Object]  optional data attached to the event:
+  #                            - final/halted context for :finished/:halted
+  #                            - Exception for :error
+  #                            - nil for :start / :state_completed
+  Event = Data.define(:type, :target_id, :payload)
+end

data/lib/phronomy/event_loop.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Singleton event loop that manages all FSMSession instances.
+  #
+  # A single background thread reads from a global Thread::Queue and dispatches
+  # events to their target FSMSession. IO work (LLM calls, tool calls) runs in
+  # separate IO threads that post events back to the loop via EventLoop#post.
+  #
+  # Activated with: +Phronomy.configure { |c| c.event_loop = true }+
+  #
+  # == Fork safety
+  #
+  # +EventLoop.instance+ is lazily initialized. The background thread is not
+  # created until the first call, so Puma worker forking does not duplicate the
+  # thread. No +after_fork+ hook is required.
+  #
+  # == Deadlock warning
+  #
+  # Do NOT call +Workflow#invoke+ (in EventLoop mode) from within a workflow
+  # entry action. The entry action runs on the EventLoop thread; a nested
+  # +invoke+ would block waiting for the same thread to process events →
+  # deadlock. Use the async IO pattern instead (spawn a Thread, post events
+  # back to the EventLoop).
+  class EventLoop
+    # Returns the singleton instance, creating and starting it on first call.
+    def self.instance
+      @instance ||= new.tap(&:start)
+    end
+
+    # Stops and destroys the singleton. Primarily used in tests.
+    # @api private
+    def self.reset!
+      @instance&.stop
+      @instance = nil
+    end
+
+    def initialize
+      @queue = Thread::Queue.new  # global event queue (thread-safe; no Mutex needed)
+      @fsms = {}                 # { id => FSMSession }     — EventLoop thread only
+      @waiting = {}                 # { id => completion_queue } — EventLoop thread only
+    end
+
+    # Registers an FSMSession for execution and returns a completion queue.
+    #
+    # The session and its completion queue are handed off to the EventLoop thread
+    # via the queue payload, so +@fsms+ and +@waiting+ are exclusively written
+    # and read by the EventLoop thread. No Mutex is required.
+    #
+    # The caller blocks on +completion_queue.pop+ to receive the final context
+    # (WorkflowContext) once the workflow finishes or halts. If an error occurred,
+    # the popped value will be an Exception — callers are responsible for re-raising it.
+    #
+    # @param fsm_session [Phronomy::FSMSession]
+    # @return [Thread::Queue] resolves to final/halted context, or an Exception
+    def register(fsm_session)
+      if Thread.current[:phronomy_event_loop_thread]
+        raise Phronomy::Error,
+          "Cannot call Workflow#invoke (EventLoop mode) from within an EventLoop " \
+          "entry action. Use the async IO pattern: spawn a Thread, post events " \
+          "back via Phronomy::EventLoop.instance.post(...) instead."
+      end
+
+      completion_queue = Thread::Queue.new
+      # Pass both session and completion_queue in the event payload so that the
+      # EventLoop thread is the sole writer of @fsms and @waiting.
+      @queue.push(Event.new(type: :start, target_id: fsm_session.id,
+        payload: {session: fsm_session, completion: completion_queue}))
+      completion_queue
+    end
+
+    # Enqueues an {AgentFSM} as a fire-and-forget child session.
+    #
+    # Unlike {#register}, this method:
+    # - Is safe to call from the EventLoop thread (entry actions).
+    # - Does NOT block — no completion queue is created.
+    # - Delegates `:finished`/`:error` cleanup to the EventLoop via posted events.
+    #
+    # @param agent_fsm [Phronomy::Agent::FSM]
+    # @return [nil]
+    def enqueue_child(agent_fsm)
+      @queue.push(Event.new(type: :start, target_id: agent_fsm.id,
+        payload: {session: agent_fsm, completion: nil}))
+      nil
+    end
+
+    # Posts an event to the loop. Safe to call from any thread (including IO threads).
+    #
+    # @param event [Phronomy::Event]
+    def post(event)
+      @queue.push(event)
+    end
+
+    # Starts the background event loop thread.
+    # @return [self]
+    def start
+      @running = true
+      @thread = Thread.new do
+        Thread.current[:phronomy_event_loop_thread] = true
+        run_loop
+      end
+      @thread.abort_on_exception = false
+      self
+    end
+
+    # Stops the background thread. Used in tests only.
+    # @api private
+    def stop
+      @running = false
+      @thread&.kill
+      @thread = nil
+    end
+
+    private
+
+    def run_loop
+      while @running
+        event = @queue.pop
+
+        case event.type
+        when :finished, :halted, :error
+          # All three terminal events share the same cleanup path.
+          # Both @fsms and @waiting are exclusively owned by this thread.
+          @fsms.delete(event.target_id)
+          cq = @waiting.delete(event.target_id)
+          cq&.push(event.payload)
+
+        when :start
+          # session and completion_queue arrive together in the payload so that
+          # this thread is the sole writer of @fsms and @waiting.
+          # completion may be nil for fire-and-forget child sessions (AgentFSM).
+          @fsms[event.target_id] = event.payload[:session]
+          cq = event.payload[:completion]
+          @waiting[event.target_id] = cq if cq
+          event.payload[:session].start
+
+        else
+          @fsms[event.target_id]&.handle(event)
+        end
+      end
+    rescue => e
+      # Unblock all waiting callers if the loop dies unexpectedly.
+      @waiting.values.each { |cq| cq.push(e) }
+      raise
+    end
+  end
+end

data/lib/phronomy/fsm_session.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Event-driven execution wrapper for a single workflow run.
+  #
+  # Created by WorkflowRunner and registered with EventLoop. All public methods
+  # are called from the EventLoop thread — FSMSession is NOT thread-safe and must
+  # not be accessed concurrently from multiple threads.
+  #
+  # == Lifecycle
+  #
+  #   register(session) → EventLoop posts :start → session.start
+  #                                 ↓ (auto-transition present)
+  #                        EventLoop posts :state_completed → session.handle
+  #                                 ↓ (repeat)
+  #                        session posts :finished or :halted
+  #                                 ↓
+  #                        EventLoop pushes ctx to completion_queue → caller unblocks
+  #
+  # == Async IO pattern (EventLoop mode only)
+  #
+  # When a state has no auto-transition and is not a wait_state, but has an
+  # external event registered (e.g. +transition from: :fetching, on: :fetch_done+),
+  # the FSMSession stays registered in the EventLoop and waits for that event.
+  # The entry action is expected to spawn an IO thread that posts the event back:
+  #
+  #   entry :fetching, ->(ctx) {
+  #     Thread.new {
+  #       ctx.result = http.get(ctx.url)
+  #       Phronomy::EventLoop.instance.post(
+  #         Phronomy::Event.new(type: :fetch_done, target_id: ctx.thread_id, payload: nil)
+  #       )
+  #     }
+  #   }
+  #   transition from: :fetching, on: :fetch_done, to: :process
+  class FSMSession
+    FINISH = WorkflowRunner::FINISH
+
+    # @return [String] workflow thread_id (matches WorkflowContext#thread_id)
+    attr_reader :id
+
+    # @param id                  [String]
+    # @param context             [Object]        includes Phronomy::WorkflowContext
+    # @param entry_point         [Symbol]        initial state name
+    # @param entry_actions       [Hash]          { state_name => [callable, ...] }
+    # @param auto_state_set      [Hash]          { state_name => true }
+    # @param declared_states     [Array<Symbol>] all action state names
+    # @param wait_state_names    [Array<Symbol>]
+    # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
+    # @param phase_machine_class [Class]         state_machines-backed phase tracker class
+    # @param recursion_limit     [Integer]
+    # @param resume_event        [Symbol, nil]   external event to fire when resuming
+    # @param resume_phase        [Symbol, nil]   wait state name to resume from
+    def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
+      declared_states:, wait_state_names:, external_events:, phase_machine_class:,
+      recursion_limit:, resume_event: nil, resume_phase: nil)
+      @id = id
+      @ctx = 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
+      @step = 0
+      @done = false
+      @current_state = nil
+      @tracker = nil
+    end
+
+    # Begins workflow execution. Called by EventLoop on :start event.
+    def start
+      if @resume_event
+        # Resume from wait state: position tracker at the wait state, then fire the
+        # external event. state_machines fires before_transition (exit) and
+        # after_transition (entry) callbacks, so both actions execute here.
+        @current_state = @resume_phase
+        @tracker = build_tracker(@current_state)
+        @tracker.context = @ctx
+        fire_and_advance!(@resume_event)
+      else
+        # Fresh start: state_machines does not fire callbacks on initialization,
+        # so we invoke the entry action for the initial state manually.
+        @current_state = @entry_point
+        @tracker = build_tracker(@current_state)
+        @tracker.context = @ctx
+        (@entry_actions[@current_state] || []).each { |c| c.call(@ctx) }
+        advance_or_halt
+      end
+    rescue => e
+      finish_with_error(e)
+    end
+
+    # Processes an event dispatched from EventLoop.
+    # Called for :state_completed and all user-defined external events.
+    #
+    # @param event [Phronomy::Event]
+    def handle(event)
+      return if @done
+
+      fire_and_advance!(event.type)
+    rescue => e
+      finish_with_error(e)
+    end
+
+    private
+
+    # Fires event_name on the phase tracker, updates @current_state, then
+    # calls advance_or_halt to decide what to do next.
+    def fire_and_advance!(event_name)
+      if @step >= @recursion_limit
+        raise Phronomy::RecursionLimitError,
+          "Recursion limit (#{@recursion_limit}) exceeded"
+      end
+
+      fire_event!(@tracker, event_name, @current_state)
+      next_phase = @tracker.phase.to_sym
+      # When next_phase == @current_state, no transition matched → treat as terminal.
+      @current_state = (next_phase == @current_state) ? FINISH : next_phase
+      @step += 1
+      advance_or_halt
+    end
+
+    # Determines the next action after the FSM has entered @current_state.
+    def advance_or_halt
+      return finish! if @current_state == FINISH
+
+      if @wait_state_names.include?(@current_state)
+        return halt!
+      end
+
+      if @auto_state_set.key?(@current_state)
+        event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
+        return
+      end
+
+      if has_external_event_from?(@current_state)
+        # Async IO pattern: the entry action spawned an IO thread that will post
+        # an external event back. Stay registered; do nothing here.
+        return
+      end
+
+      # No transition declared — validate the state is known, then treat as terminal.
+      unless @declared_states.include?(@current_state)
+        raise ArgumentError, "State #{@current_state.inspect} is not defined"
+      end
+
+      finish!
+    end
+
+    def finish!
+      @done = true
+      @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
+      event_loop.post(Event.new(type: :finished, target_id: @id, payload: @ctx))
+    end
+
+    def halt!
+      @done = true
+      @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
+      event_loop.post(Event.new(type: :halted, target_id: @id, payload: @ctx))
+    end
+
+    def finish_with_error(err)
+      @done = true
+      event_loop.post(Event.new(type: :error, target_id: @id, payload: err))
+    end
+
+    def fire_event!(tracker, event_name, from_state)
+      return if tracker.send(event_name)
+
+      raise ArgumentError,
+        "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
+
+    def has_external_event_from?(state)
+      @external_events.any? { |_, transitions| transitions.any? { |t| t[:from] == state } }
+    end
+
+    def build_tracker(from_state)
+      machine = @phase_machine_class.new
+      machine.instance_variable_set(:@phase, from_state.to_s)
+      machine
+    end
+
+    def event_loop
+      Phronomy::EventLoop.instance
+    end
+  end
+end

data/lib/phronomy/generator_verifier.rb

@@ -133,7 +133,7 @@ module Phronomy
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
       @raise_if_untrusted = raise_if_untrusted
-      @compiled_graph = nil
+      @compiled_workflow = nil
     end
 
     # Run the generator-verifier pipeline.
@@ -144,7 +144,7 @@ module Phronomy
     # @raise [Phronomy::LowConfidenceError] when +raise_if_untrusted:+ is +true+
     #   and the result does not meet the confidence threshold
     def invoke(input, config: {})
-      app = compiled_graph
+      app = compiled_workflow
       state = app.invoke({input: input}, config: config)
       confidence = combined_confidence(state)
       trusted = confidence >= @threshold
@@ -166,8 +166,8 @@ module Phronomy
       [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
     end
 
-    def compiled_graph
-      @compiled_graph ||= build_workflow
+    def compiled_workflow
+      @compiled_workflow ||= build_workflow
     end
 
     def build_workflow
@@ -184,42 +184,42 @@ module Phronomy
       Phronomy::Workflow.define(PipelineState) do
         initial :draft
 
-        state :draft, action: ->(state) {
+        state :draft
+        state :review
+        state :finalize
+
+        entry :draft, ->(state) {
           feedback = state.review_notes.last
           prompt = dpb.call(state.input, feedback)
           result = draft_agent.invoke(prompt)
           parsed = drp.call(result[:output])
-          state.merge(
-            draft: parsed[:answer].to_s,
-            self_score: pipeline.__send__(:clamp, parsed[:confidence]),
-            citations: pipeline.__send__(:normalize_citations, parsed[:citations]),
-            iteration: state.iteration + 1
-          )
+          state.draft = parsed[:answer].to_s
+          state.self_score = pipeline.__send__(:clamp, parsed[:confidence])
+          state.citations = pipeline.__send__(:normalize_citations, parsed[:citations])
+          state.iteration = state.iteration + 1
         }
 
-        state :review, action: ->(state) {
+        entry :review, ->(state) {
           prompt = rpb.call(state.input, state.draft, state.citations)
           result = review_agent.invoke(prompt)
           parsed = rrp.call(result[:output])
-          state.merge(
-            review_score: pipeline.__send__(:clamp, parsed[:score]),
-            approved: parsed[:approved] == true,
-            review_notes: parsed[:feedback].to_s
-          )
+          state.review_score = pipeline.__send__(:clamp, parsed[:score])
+          state.approved = parsed[:approved] == true
+          state.review_notes << parsed[:feedback].to_s
         }
 
-        state :finalize, action: ->(state) { state.merge(output: state.draft) }
+        entry :finalize, ->(state) { state.output = state.draft }
 
-        after :draft, to: :review
-        after :finalize, to: :__finish__
+        transition from: :draft, to: :review
+        transition from: :finalize, to: :__finish__
 
-        event :route_review, from: :review,
+        transition from: :review,
           guard: ->(state) {
             confidence = [state.self_score || 0.0, state.review_score || 0.0].min
             (confidence >= threshold && state.approved) || state.iteration >= max_iter
           },
           to: :finalize
-        event :route_review, from: :review, to: :draft
+        transition from: :review, to: :draft
       end
     end
 

data/lib/phronomy/guardrail.rb

@@ -5,4 +5,3 @@
 require_relative "guardrail/base"
 require_relative "guardrail/input_guardrail"
 require_relative "guardrail/output_guardrail"
-require_relative "guardrail/builtin"

data/lib/phronomy/vector_store/base.rb

@@ -36,6 +36,21 @@ module Phronomy
       def clear
         raise NotImplementedError, "#{self.class}#clear is not implemented"
       end
+
+      private
+
+      # Validates that embedding has the expected dimension.
+      # Raises ArgumentError if sizes differ.
+      # A nil expected_dimension is a no-op (dimension not yet established).
+      def validate_embedding_dimension!(embedding, expected_dimension)
+        return unless expected_dimension
+
+        actual = embedding.size
+        return if actual == expected_dimension
+
+        raise ArgumentError,
+          "Embedding dimension mismatch: expected #{expected_dimension}, got #{actual}"
+      end
     end
   end
 end

data/lib/phronomy/vector_store/in_memory.rb

@@ -12,14 +12,22 @@ module Phronomy
     #   store.add(id: "1", embedding: [0.1, 0.9], metadata: { message: msg })
     #   results = store.search(query_embedding: [0.1, 0.8], k: 3)
     class InMemory < Base
-      def initialize
+      # @param dimension [Integer, nil] expected embedding dimension.
+      #   When nil, the dimension is inferred from the first call to #add.
+      #   For multi-threaded use, pass dimension: explicitly; concurrent first
+      #   adds are not guaranteed to be race-free.
+      def initialize(dimension: nil)
         @documents = {}
+        @expected_dimension = dimension
       end
 
       # @param id        [String]
       # @param embedding [Array<Float>]
       # @param metadata  [Hash]
       def add(id:, embedding:, metadata: {})
+        # Establish expected dimension on first add, then validate.
+        @expected_dimension ||= embedding.size
+        validate_embedding_dimension!(embedding, @expected_dimension)
         @documents[id] = {embedding: embedding, metadata: metadata}
         self
       end
@@ -28,6 +36,8 @@ module Phronomy
       # @param k               [Integer]
       # @return [Array<Hash>] sorted by descending score
       def search(query_embedding:, k: 5)
+        # search never establishes dimension; validate only when dimension is known.
+        validate_embedding_dimension!(query_embedding, @expected_dimension)
         # Take an atomic snapshot before iterating.  Hash#dup is a C-level
         # call that completes without releasing the GVL, so it is atomic with
         # respect to any other Ruby thread.  Iterating the copy instead of

data/lib/phronomy/vector_store/pgvector.rb

@@ -18,8 +18,11 @@ module Phronomy
     #   store.add(id: "doc1", embedding: [0.1, 0.9], metadata: {text: "hello"})
     #   results = store.search(query_embedding: [0.1, 0.8], k: 5)
     class Pgvector < Base
-      # @param model_class [Class] ActiveRecord model with id/embedding/metadata columns
-      def initialize(model_class:)
+      # @param model_class [Class]        ActiveRecord model with id/embedding/metadata columns
+      # @param dimension   [Integer, nil] expected embedding dimension for Phronomy-side
+      #   pre-validation.  When nil, dimension enforcement is delegated to the
+      #   database schema; no pre-validation is performed by Phronomy.
+      def initialize(model_class:, dimension: nil)
         begin
           require "pgvector"
         rescue LoadError
@@ -28,12 +31,14 @@ module Phronomy
             "Add `gem 'pgvector'` to your Gemfile."
         end
         @model_class = model_class
+        @dimension = dimension
       end
 
       # @param id        [String]
       # @param embedding [Array<Float>]
       # @param metadata  [Hash]
       def add(id:, embedding:, metadata: {})
+        validate_embedding_dimension!(embedding, @dimension)
         @model_class.upsert(
           {id: id, embedding: safe_vector(embedding), metadata: metadata.to_json},
           unique_by: :id
@@ -45,6 +50,7 @@ module Phronomy
       # @param k               [Integer]
       # @return [Array<Hash>] sorted by descending similarity score
       def search(query_embedding:, k: 5)
+        validate_embedding_dimension!(query_embedding, @dimension)
         vec = safe_vector_literal(query_embedding)
         k_safe = Integer(k)
         conn = @model_class.connection

data/lib/phronomy/vector_store/redis_search.rb

@@ -25,7 +25,11 @@ module Phronomy
 
       # @param redis      [Redis]          configured Redis client
       # @param index_name [String]         RediSearch index name
-      # @param dimension  [Integer, nil]   vector dimension; auto-detected on first add
+      # @param dimension  [Integer, nil]   vector dimension; auto-detected on first add.
+      #   When connecting to an **existing** RediSearch index, you MUST pass
+      #   dimension: explicitly.  Without it, a freshly constructed instance
+      #   treats the index as uninitialized until #add is called, and #search
+      #   silently returns [] in the meantime.
       def initialize(redis:, index_name: "phronomy_vectors", dimension: nil)
         begin
           require "redis"
@@ -45,7 +49,11 @@ module Phronomy
       # @param embedding [Array<Float>]
       # @param metadata  [Hash]
       def add(id:, embedding:, metadata: {})
-        ensure_index!(embedding.length)
+        # Establish expected dimension on first add (not race-free for concurrent
+        # first adds), then validate, then create/reuse the index.
+        @dimension ||= embedding.size
+        validate_embedding_dimension!(embedding, @dimension)
+        ensure_index!(@dimension)
         @redis.call(
           "HSET", "#{DOC_PREFIX}#{id}",
           "embedding", pack_vector(embedding),
@@ -58,7 +66,12 @@ module Phronomy
       # @param k               [Integer]
       # @return [Array<Hash>] sorted by descending similarity score
       def search(query_embedding:, k: 5)
-        ensure_index!(query_embedding.length)
+        # search never establishes dimension.  If dimension is unknown and the
+        # index has not been created yet, there are no documents to return.
+        return [] if @dimension.nil? && !@index_created
+
+        validate_embedding_dimension!(query_embedding, @dimension)
+        ensure_index!(@dimension)
         k_safe = Integer(k)
         blob = pack_vector(query_embedding)
 

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end