phronomy 0.1.3 → 0.2.0

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: -> {}
@@ -75,14 +75,21 @@ module Phronomy
     # @param review_agent         [Class]   subclass of Phronomy::Agent::Base
     # @param confidence_threshold [Float]   answers below this are retried (default: 0.7)
     # @param max_iterations       [Integer] maximum draft-review cycles (default: 3)
+    # @param input_delimiter      [Array<String>, nil] optional two-element array
+    #   [start_tag, end_tag] used to wrap user input in prompts, e.g.
+    #   ["<user_input>", "</user_input>"] or
+    #   ["=== user input start ===", "=== user input end ==="].
+    #   When nil (default), input is embedded as-is for backward compatibility.
     def initialize(draft_agent:, review_agent:,
       confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
-      max_iterations: DEFAULT_MAX_ITERATIONS)
+      max_iterations: DEFAULT_MAX_ITERATIONS,
+      input_delimiter: nil)
       @draft_agent_class = draft_agent
       @review_agent_class = review_agent
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
-      @graph_mutex = Mutex.new
+      @input_delimiter = input_delimiter
+      @actor = Phronomy::Actor.new
       @compiled_graph = nil
     end
 
@@ -111,66 +118,67 @@ 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)
-
-      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
+      Phronomy::Workflow.define(PipelineState) do
+        initial :draft
 
-      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 :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
+          )
+        }
+
+        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
+          )
+        }
+
+        state :finalize, action: ->(state) { state.merge(output: state.draft) }
+
+        after :draft, to: :review
+        after :finalize, to: :__finish__
 
-      graph.add_node(:finalize) do |state|
-        state.merge(output: state.draft)
+        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
 
-      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)
+    # Wraps +input+ with the configured delimiter pair when +input_delimiter+ is set.
+    # When no delimiter is configured the input is returned unchanged.
+    def wrap_input(input)
+      return input unless @input_delimiter
 
-      graph
+      start_tag, end_tag = @input_delimiter
+      "#{start_tag}\n#{input}\n#{end_tag}"
     end
 
     # Builds the prompt sent to the DraftAgent for each iteration.
@@ -186,7 +194,7 @@ module Phronomy
       end
       lines += [
         "",
-        "Question: #{input}",
+        "Question: #{wrap_input(input)}",
         "",
         "RESPOND ONLY WITH VALID JSON (no text outside the JSON block):",
         '{"answer":"<full answer>","confidence":<0.0-1.0>,' \
@@ -205,7 +213,7 @@ module Phronomy
       [
         "You are a rigorous quality reviewer. Evaluate the draft answer below.",
         "",
-        "Question: #{input}",
+        "Question: #{wrap_input(input)}",
         "",
         "Draft answer:",
         draft.to_s,

data/lib/phronomy/vector_store/redis_search.rb

@@ -38,6 +38,7 @@ module Phronomy
         @index_name = index_name
         @dimension = dimension
         @index_created = false
+        @actor = Phronomy::Actor.new
       end
 
       # @param id        [String]
@@ -79,37 +80,41 @@ module Phronomy
       end
 
       def clear
-        begin
-          @redis.call("FT.DROPINDEX", @index_name, "DD")
-        rescue => e
-          raise unless e.message.to_s.include?("Unknown Index name")
+        @actor.call do
+          begin
+            @redis.call("FT.DROPINDEX", @index_name, "DD")
+          rescue => e
+            raise unless e.message.to_s.include?("Unknown Index name")
+          end
+          @index_created = false
         end
-        @index_created = false
         self
       end
 
       private
 
       def ensure_index!(dim)
-        return if @index_created
-
-        @dimension ||= dim
-        begin
-          @redis.call(
-            "FT.CREATE", @index_name,
-            "ON", "HASH",
-            "PREFIX", 1, DOC_PREFIX,
-            "SCHEMA",
-            "embedding", "VECTOR", "FLAT", 6,
-            "TYPE", "FLOAT32",
-            "DIM", @dimension,
-            "DISTANCE_METRIC", "COSINE",
-            "metadata", "TEXT"
-          )
-        rescue => e
-          raise unless e.message.to_s.include?("Index already exists")
+        @actor.call do
+          next if @index_created
+
+          @dimension ||= dim
+          begin
+            @redis.call(
+              "FT.CREATE", @index_name,
+              "ON", "HASH",
+              "PREFIX", 1, DOC_PREFIX,
+              "SCHEMA",
+              "embedding", "VECTOR", "FLAT", 6,
+              "TYPE", "FLOAT32",
+              "DIM", @dimension,
+              "DISTANCE_METRIC", "COSINE",
+              "metadata", "TEXT"
+            )
+          rescue => e
+            raise unless e.message.to_s.include?("Index already exists")
+          end
+          @index_created = true
         end
-        @index_created = true
       end
 
       # Pack a Float array as a FLOAT32 binary string for RediSearch.

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow.rb

@@ -0,0 +1,281 @@
+# 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
+    # @yield block evaluated in DSL context
+    # @return [Phronomy::Workflow] compiled and ready-to-run workflow instance
+    def self.define(context_class, &block)
+      builder = Builder.new(context_class)
+      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)
+        @context_class = context_class
+        @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
+        edges = build_edges
+        conditional_edges = build_conditional_edges
+        wait_states = build_wait_states
+
+        runner = Phronomy::WorkflowRunner.new(
+          state_class: @context_class,
+          nodes: nodes,
+          edges: edges,
+          conditional_edges: conditional_edges,
+          entry_point: @initial || nodes.keys.first,
+          wait_states: wait_states
+        )
+
+        Workflow.new(runner)
+      end
+
+      private
+
+      # Converts @after_transitions and non-guarded @event_transitions into
+      # the edges hash expected by WorkflowRunner: { from => [{to:, condition:}] }
+      #
+      # Event transitions whose from-node also has guarded transitions are omitted
+      # here; they are handled inside build_conditional_edges as a fallback.
+      def build_edges
+        edges = {}
+
+        # After-transitions (unconditional edges fired after action completes)
+        @after_transitions.each do |t|
+          edges[t[:from]] ||= []
+          edges[t[:from]] << {to: t[:to], condition: nil}
+        end
+
+        # Collect from-nodes that already have at least one guarded event
+        from_with_guards = @event_transitions.select { |t| t[:guard] }.map { |t| t[:from] }.to_set
+
+        # Unconditional event transitions are plain edges ONLY when no guarded
+        # event exists from the same source node.  When guards are present the
+        # unguarded transition acts as a fallback and is wired inside
+        # build_conditional_edges instead.
+        @event_transitions.reject { |t| t[:guard] }.each do |t|
+          next if from_with_guards.include?(t[:from])
+          edges[t[:from]] ||= []
+          edges[t[:from]] << {to: t[:to], condition: nil}
+        end
+
+        edges
+      end
+
+      # Converts guarded event transitions into the conditional_edges hash:
+      # { from => { condition: Proc, mapping: nil } }
+      #
+      # Multiple guarded transitions from the same source are combined into a
+      # single routing proc.  An unguarded transition from the same source is
+      # used as an automatic fallback when all guards fail.
+      def build_conditional_edges
+        conditional_edges = {}
+
+        guarded = @event_transitions.select { |t| t[:guard] }
+        guarded.group_by { |t| t[:from] }.each do |from, transitions|
+          # Unguarded fallback for this from-node (may be nil)
+          fallback = @event_transitions.find { |t| t[:from] == from && t[:guard].nil? }
+
+          routing = lambda do |state|
+            matched = transitions.find { |t| t[:guard].call(state) }
+            next matched[:to] if matched
+            fallback&.fetch(:to)
+          end
+          conditional_edges[from] = {condition: routing, mapping: nil}
+        end
+
+        conditional_edges
+      end
+
+      # Converts wait_state declarations plus event-driven transitions *to*
+      # wait states into the wait_states hash:
+      # { wait_state_name => { resume_event: Symbol, resume_to: Symbol } }
+      #
+      # For each wait state, we look for the first event declared as
+      # `event :X, from: :wait_state_name, to: :Y` and use that as the
+      # resume_event / resume_to pair. If multiple events exist for the same
+      # wait state, subsequent ones are registered as additional named events.
+      def build_wait_states
+        wait_states = {}
+
+        @wait_state_names.each do |ws|
+          # Find events that originate from this wait state
+          outgoing = @event_transitions.select { |t| t[:from] == ws }
+          primary = outgoing.first
+
+          wait_states[ws] = {
+            resume_event: primary&.fetch(:name),
+            resume_to: primary&.fetch(:to)
+          }
+
+          # Additional events from the same wait state are also registered so
+          # that send_event(:other_event) works for branching wait states.
+          outgoing.drop(1).each do |t|
+            wait_states[:"#{ws}__#{t[:name]}"] = {
+              resume_event: t[:name],
+              resume_to: t[:to]
+            }
+          end
+        end
+
+        wait_states
+      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