phronomy 0.1.4 → 0.2.1

data/lib/phronomy/trust_pipeline.rb

@@ -56,7 +56,7 @@ module Phronomy
     # Internal graph state — not part of the public API.
     # @private
     class PipelineState
-      include Phronomy::Graph::State
+      include Phronomy::WorkflowContext
 
       field :input, type: :replace, default: -> { "" }
       field :draft, type: :replace, default: -> {}
@@ -89,7 +89,7 @@ module Phronomy
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
       @input_delimiter = input_delimiter
-      @graph_mutex = Mutex.new
+      @actor = Phronomy::Actor.new
       @compiled_graph = nil
     end
 
@@ -118,66 +118,58 @@ module Phronomy
       [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
     end
 
-    # Returns the compiled graph, building and caching it on first call.
-    # Thread-safe via double-checked locking.
+    # Returns the compiled workflow, building and caching it on first call.
     def compiled_graph
-      return @compiled_graph if @compiled_graph
-
-      @graph_mutex.synchronize do
-        @compiled_graph ||= build_graph.compile
-      end
+      @actor.call { @compiled_graph ||= build_workflow }
     end
 
-    def build_graph
+    def build_workflow
       draft_agent = @draft_agent_class.new
       review_agent = @review_agent_class.new
       threshold = @threshold
       max_iter = @max_iterations
+      pipeline = self
 
-      graph = Phronomy::Graph::StateGraph.new(PipelineState)
+      Phronomy::Workflow.define(PipelineState) do
+        initial :draft
 
-      graph.add_node(:draft) do |state|
-        feedback = state.review_notes.last
-        prompt = draft_prompt(state.input, feedback)
-        result = draft_agent.invoke(prompt)
-        parsed = safe_parse_draft(result[:output])
-        state.merge(
-          draft: parsed[:answer].to_s,
-          self_score: clamp(parsed[:confidence]),
-          citations: normalize_citations(parsed[:citations]),
-          iteration: state.iteration + 1
-        )
-      end
+        state :draft, action: ->(state) {
+          feedback = state.review_notes.last
+          prompt = pipeline.__send__(:draft_prompt, state.input, feedback)
+          result = draft_agent.invoke(prompt)
+          parsed = pipeline.__send__(:safe_parse_draft, 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
+          )
+        }
 
-      graph.add_node(:review) do |state|
-        prompt = review_prompt(state.input, state.draft, state.citations)
-        result = review_agent.invoke(prompt)
-        parsed = safe_parse_review(result[:output])
-        state.merge(
-          review_score: clamp(parsed[:score]),
-          approved: parsed[:approved] == true,
-          review_notes: parsed[:feedback].to_s
-        )
-      end
+        state :review, action: ->(state) {
+          prompt = pipeline.__send__(:review_prompt, state.input, state.draft, state.citations)
+          result = review_agent.invoke(prompt)
+          parsed = pipeline.__send__(:safe_parse_review, result[:output])
+          state.merge(
+            review_score: pipeline.__send__(:clamp, parsed[:score]),
+            approved: parsed[:approved] == true,
+            review_notes: parsed[:feedback].to_s
+          )
+        }
 
-      graph.add_node(:finalize) do |state|
-        state.merge(output: state.draft)
-      end
+        state :finalize, action: ->(state) { state.merge(output: state.draft) }
 
-      graph.set_entry_point(:draft)
-      graph.add_edge(:draft, :review)
-      graph.add_conditional_edges(
-        :review,
-        ->(state) {
-          confidence = [state.self_score || 0.0, state.review_score || 0.0].min
-          passed = confidence >= threshold && state.approved
-          exhausted = state.iteration >= max_iter
-          (passed || exhausted) ? :finalize : :draft
-        }
-      )
-      graph.add_edge(:finalize, Phronomy::Graph::StateGraph::FINISH)
+        after :draft, to: :review
+        after :finalize, to: :__finish__
 
-      graph
+        event :route_review, 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
+      end
     end
 
     # Wraps +input+ with the configured delimiter pair when +input_delimiter+ is set.

data/lib/phronomy/vector_store/in_memory.rb

@@ -14,14 +14,13 @@ module Phronomy
     class InMemory < Base
       def initialize
         @documents = {}
-        @mutex = Mutex.new
       end
 
       # @param id        [String]
       # @param embedding [Array<Float>]
       # @param metadata  [Hash]
       def add(id:, embedding:, metadata: {})
-        @mutex.synchronize { @documents[id] = {embedding: embedding, metadata: metadata} }
+        @documents[id] = {embedding: embedding, metadata: metadata}
         self
       end
 
@@ -29,8 +28,7 @@ module Phronomy
       # @param k               [Integer]
       # @return [Array<Hash>] sorted by descending score
       def search(query_embedding:, k: 5)
-        snapshot = @mutex.synchronize { @documents.dup }
-        results = snapshot.map do |id, doc|
+        results = @documents.map do |id, doc|
           score = cosine_similarity(query_embedding, doc[:embedding])
           {id: id, score: score, metadata: doc[:metadata]}
         end
@@ -38,18 +36,18 @@ module Phronomy
       end
 
       def remove(id:)
-        @mutex.synchronize { @documents.delete(id) }
+        @documents.delete(id)
         self
       end
 
       def clear
-        @mutex.synchronize { @documents.clear }
+        @documents.clear
         self
       end
 
       # @return [Integer] number of documents stored
       def size
-        @mutex.synchronize { @documents.size }
+        @documents.size
       end
 
       private

data/lib/phronomy/vector_store/redis_search.rb

@@ -38,7 +38,7 @@ module Phronomy
         @index_name = index_name
         @dimension = dimension
         @index_created = false
-        @mutex = Mutex.new
+        @actor = Phronomy::Actor.new
       end
 
       # @param id        [String]
@@ -80,7 +80,7 @@ module Phronomy
       end
 
       def clear
-        @mutex.synchronize do
+        @actor.call do
           begin
             @redis.call("FT.DROPINDEX", @index_name, "DD")
           rescue => e
@@ -94,10 +94,8 @@ module Phronomy
       private
 
       def ensure_index!(dim)
-        return if @index_created # fast path outside lock
-
-        @mutex.synchronize do
-          return if @index_created # re-check inside lock
+        @actor.call do
+          next if @index_created
 
           @dimension ||= dim
           begin

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require_relative "workflow_runner"
+require_relative "runnable"
+
+module Phronomy
+  # StateChart-style workflow definition DSL.
+  #
+  # Defines agent workflows in terms of *states* and *events* backed by
+  # Phronomy::WorkflowRunner. This is the primary high-level API
+  # for graph-based execution in phronomy.
+  #
+  # == Basic usage
+  #
+  #   app = Phronomy::Workflow.define(MyContext) do
+  #     initial :fetch
+  #
+  #     state :fetch,   action: FETCH_NODE
+  #     state :process, action: PROCESS_NODE
+  #
+  #     after :fetch,   to: :process
+  #     after :process, to: :__finish__
+  #   end
+  #
+  #   result = app.invoke({ url: "https://example.com" })
+  #
+  # == Wait states
+  #
+  #   app = Phronomy::Workflow.define(MyContext) do
+  #     initial :propose
+  #
+  #     state :propose, action: PROPOSE_NODE
+  #     wait_state :awaiting_approval
+  #     state :execute, action: EXECUTE_NODE
+  #
+  #     after :propose, to: :awaiting_approval
+  #     after :execute, to: :__finish__
+  #
+  #     event :approve, from: :awaiting_approval, to: :execute
+  #     event :reject,  from: :awaiting_approval, to: :propose
+  #   end
+  #
+  #   halted = app.invoke({ ... })
+  #   final  = app.send_event(state: halted, event: :approve)
+  #
+  # == Conditional transitions
+  #
+  #   event :route, from: :decide, guard: ->(s) { s.score > 5 }, to: :high
+  #   event :route, from: :decide, to: :low   # fallback (no guard)
+  #
+  class Workflow
+    include Phronomy::Runnable
+
+    # Defines a new Workflow.
+    # @param context_class [Class] class that includes Phronomy::WorkflowContext
+    # @param state_store [Object, nil] optional state store override (passed to WorkflowRunner)
+    # @yield block evaluated in DSL context
+    # @return [Phronomy::Workflow] compiled and ready-to-run workflow instance
+    def self.define(context_class, state_store: nil, &block)
+      builder = Builder.new(context_class, state_store: state_store)
+      builder.instance_eval(&block)
+      builder.build
+    end
+
+    # @param runner [Phronomy::WorkflowRunner]
+    def initialize(runner)
+      @runner = runner
+    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
+    def invoke(input, config: {})
+      @runner.invoke(input, config: config)
+    end
+
+    # Resumes a halted workflow. Generic resume that works for all halt types.
+    # @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)
+      @runner.resume(state: state, input: input)
+    end
+
+    # Fires a named event to advance a halted workflow.
+    # @param state [Object] halted context
+    # @param event [Symbol] event name (e.g. :approve, :reject, :resume)
+    # @param input [Hash, nil] optional field updates to merge before resuming
+    # @return [Object] final context
+    def send_event(state:, event:, input: nil)
+      @runner.send_event(state: state, event: event, input: input)
+    end
+
+    # Streaming execution. Yields { node: Symbol, state: Object } after each node.
+    # @param input [Hash]
+    # @param config [Hash]
+    # @yield [Hash]
+    # @return [Object] final context
+    def stream(input, config: {}, &block)
+      @runner.stream(input, config: config, &block)
+    end
+
+    # ---------------------------------------------------------------------------
+    # Internal DSL builder
+    # ---------------------------------------------------------------------------
+
+    # DSL builder for Phronomy::Workflow.define.
+    # Collects state/event/transition declarations and produces a WorkflowRunner.
+    class Builder
+      FINISH = Phronomy::WorkflowRunner::FINISH
+
+      def initialize(context_class, state_store: nil)
+        @context_class = context_class
+        @state_store = state_store
+        @initial = nil
+        # { node_name => callable }
+        @states = {}
+        # Array of { from:, to: } — auto-transitions after a state action
+        @after_transitions = []
+        # Array of { name:, from:, to:, guard: } — event-driven transitions
+        @event_transitions = []
+        # Set of wait state names
+        @wait_state_names = []
+      end
+
+      # Declares the initial (entry) state.
+      # @param state_name [Symbol]
+      # rubocop:disable Style/TrivialAccessors
+      def initial(state_name)
+        @initial = state_name
+      end
+      # rubocop:enable Style/TrivialAccessors
+
+      # Declares an action state.
+      # @param name [Symbol] state name
+      # @param action [#call, nil] callable invoked when entering the state.
+      #   If nil, the state is treated as a no-op pass-through.
+      def state(name, action: nil)
+        @states[name] = action || ->(s) { s }
+      end
+
+      # Declares a wait state that automatically halts execution when reached.
+      # No action is registered; the workflow pauses here until an event resumes it.
+      # @param name [Symbol] wait state name (conventionally :awaiting_something)
+      def wait_state(name)
+        @wait_state_names << name
+      end
+
+      # Declares an automatic transition that fires after a state's action completes.
+      # @param from [Symbol] source state name
+      # @param to [Symbol] destination state name or :__finish__
+      def after(from, to:)
+        dest = (to == :__finish__) ? FINISH : to
+        @after_transitions << {from: from, to: dest}
+      end
+
+      # Declares an event-driven transition.
+      # When +guard:+ is provided, the transition is taken only if the guard
+      # returns truthy for the current context. Multiple events with the same
+      # name and source are evaluated in declaration order; the first passing
+      # guard wins.
+      # @param name [Symbol] event name
+      # @param from [Symbol] source state where this event can be fired
+      # @param to [Symbol] destination state or :__finish__
+      # @param guard [Proc, nil] optional guard — receives context, returns truthy/falsy
+      def event(name, from:, to:, guard: nil)
+        dest = (to == :__finish__) ? FINISH : to
+        @event_transitions << {name: name, from: from, to: dest, guard: guard}
+      end
+
+      # Builds and returns a Phronomy::Workflow backed by a WorkflowRunner.
+      def build
+        nodes = @states.dup
+
+        # After-transitions: { from => to }
+        # Unconditional transitions that fire automatically after an action state completes.
+        after_transitions = @after_transitions.each_with_object({}) do |t, h|
+          h[t[:from]] = t[:to]
+        end
+
+        # Route transitions: { from => {event_name:, entries: [{guard:, to:}, ...]} }
+        # Events declared from action states (not wait states) fire automatically
+        # after the action completes. The event name is used to register the
+        # state_machines event and may be any symbol (e.g. :route, :route_review).
+        # Declaration order is preserved so guarded entries appear before fallbacks.
+        route_transitions = {}
+
+        # External events: { event_name => [{from:, to:, guard:}, ...] }
+        # Events declared from wait states, triggered by human input (e.g. :approve).
+        external_events = {}
+
+        @event_transitions.each do |t|
+          if @wait_state_names.include?(t[:from])
+            # Source is a wait state → external event
+            external_events[t[:name]] ||= []
+            external_events[t[:name]] << {from: t[:from], to: t[:to], guard: t[:guard]}
+          else
+            # Source is an action state → routing event (auto-fires after action)
+            # The event name is taken from the first declaration for each from-state.
+            route_transitions[t[:from]] ||= {event_name: t[:name], entries: []}
+            route_transitions[t[:from]][:entries] << {guard: t[:guard], to: t[:to]}
+          end
+        end
+
+        runner = Phronomy::WorkflowRunner.new(
+          state_class: @context_class,
+          nodes: nodes,
+          after_transitions: after_transitions,
+          route_transitions: route_transitions,
+          external_events: external_events,
+          entry_point: @initial || nodes.keys.first,
+          wait_state_names: @wait_state_names,
+          state_store: @state_store
+        )
+
+        Workflow.new(runner)
+      end
+    end
+  end
+end

data/lib/phronomy/workflow_context.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Module for defining workflow context (the data that travels through a workflow).
+  # Include in a class and use the field DSL to declare context fields.
+  #
+  # In StateChart terminology this is the "extended state" or "context" —
+  # data associated with the current execution that does not affect transitions
+  # directly, as opposed to the current phase (which is the machine's state).
+  #
+  # Field update policies:
+  #   :replace (default) -- overwrites with the new value
+  #   :append            -- appends to an Array
+  #   :merge             -- deep-merges into a Hash
+  #
+  # @example
+  #   class ScanContext
+  #     include Phronomy::WorkflowContext
+  #     field :messages, type: :append, default: -> { [] }
+  #     field :query,    type: :replace
+  #     field :metadata, type: :merge,   default: -> { {} }
+  #   end
+  module WorkflowContext
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@fields, {})
+    end
+
+    module ClassMethods
+      # Defines a context field.
+      # @param name [Symbol]
+      # @param type [Symbol] :replace / :append / :merge
+      # @param default [Object, Proc, nil]
+      def field(name, type: :replace, default: nil)
+        @fields[name] = {type: type, default: default}
+        attr_accessor name
+      end
+
+      def fields
+        @fields
+      end
+    end
+
+    # Internal workflow metadata accessors (not user-defined fields).
+    # These are preserved through merge but excluded from to_h.
+    attr_reader :thread_id
+
+    # Returns the current execution phase of the workflow.
+    # 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)
+    # @return [Symbol]
+    def phase
+      @phase || :__end__
+    end
+
+    # Returns true if the workflow is paused mid-execution (not yet completed).
+    # @return [Boolean]
+    def halted?
+      phase != :__end__
+    end
+
+    # Sets internal workflow metadata. Returns self.
+    # @param thread_id [String, nil]
+    # @param phase [Symbol, nil]
+    def set_graph_metadata(thread_id: nil, phase: nil)
+      @thread_id = thread_id unless thread_id.nil?
+      @phase = phase unless phase.nil?
+      self
+    end
+
+    def initialize(**attrs)
+      self.class.fields.each do |name, config|
+        default = config[:default].is_a?(Proc) ? config[:default].call : config[:default]
+        send(:"#{name}=", attrs.fetch(name, default))
+      end
+      @thread_id = nil
+      @phase = :__end__
+    end
+
+    # Immutably updates context fields. Returns a new instance with the applied changes.
+    # Internal workflow metadata (thread_id, phase) is preserved.
+    # @param updates [Hash] { field_name => new_value }
+    # @return [self.class] new context instance
+    def merge(updates)
+      new_attrs = {}
+      self.class.fields.each_key do |name|
+        field_config = self.class.fields[name]
+        new_attrs[name] = if updates.key?(name)
+          case field_config[:type]
+          when :append
+            Array(send(name)) + Array(updates[name])
+          when :merge
+            (send(name) || {}).merge(updates[name])
+          else
+            updates[name]
+          end
+        else
+          send(name)
+        end
+      end
+      new_context = self.class.new(**new_attrs)
+      new_context.set_graph_metadata(
+        thread_id: @thread_id,
+        phase: @phase
+      )
+      new_context
+    end
+
+    # Converts user-defined fields to a Hash (excludes internal workflow metadata).
+    # @return [Hash]
+    def to_h
+      self.class.fields.keys.each_with_object({}) do |name, h|
+        h[name] = send(name)
+      end
+    end
+  end
+end