phronomy 0.14.0 → 0.15.0

data/lib/phronomy/generator_verifier.rb

@@ -1,118 +1,81 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Phronomy
-  # Implements the Generator-Verifier multi-agent coordination pattern
-  # (Anthropic blog, Pattern 1): a generator agent produces an
-  # answer while a verifier agent evaluates its quality.
-  #
-  # @see https://claude.com/blog/multi-agent-coordination-patterns
-  #
-  # All prompt construction and result parsing are provided by the caller,
-  # giving full control over the LLM dialogue.
-  # The generator and verifier agents are configurable, and the pipeline
-  # retries until confidence passes the threshold or max iterations are reached.
-  #
-  # @example Basic usage with custom prompt builders
-  #   pipeline = Phronomy::GeneratorVerifier.new(
-  #     draft_agent:           MyDraftAgent,
-  #     review_agent:          MyReviewAgent,
-  #     draft_prompt_builder:  ->(input, feedback) { "Question: #{input}" },
-  #     review_prompt_builder: ->(input, draft, citations) { "Review: #{draft}" }
-  #   )
-  #   result = pipeline.invoke("What is the refund policy?")
-  #   puts result.output      # the final answer string
-  #   puts result.trusted?    # true when confidence >= threshold
+  # Implements the Generator-Verifier multi-agent coordination pattern.
   #
-  # @example Custom result parsers
-  #   pipeline = Phronomy::GeneratorVerifier.new(
-  #     ...,
-  #     draft_result_parser:  ->(text) { my_parse_draft(text) },
-  #     review_result_parser: ->(text) { my_parse_review(text) }
-  #   )
-  #
-  # @example Raising on low confidence
-  #   pipeline = Phronomy::GeneratorVerifier.new(
-  #     ...,
-  #     raise_if_untrusted: true
-  #   )
-  #   begin
-  #     result = pipeline.invoke("question")
-  #   rescue Phronomy::LowConfidenceError => e
-  #     puts "Untrusted: #{e.result.confidence}"
-  #   end
+  # Agent completion is integrated through application-defined Workflow events;
+  # Workflow entry actions do not return or await Agent Tasks.
   class GeneratorVerifier
-    # Default confidence threshold for trusting an answer.
     DEFAULT_CONFIDENCE_THRESHOLD = 0.7
-
-    # Default maximum draft-review cycles before returning best effort.
     DEFAULT_MAX_ITERATIONS = 3
 
-    # Immutable value object returned by {GeneratorVerifier#invoke}.
-    #
-    # @!attribute [r] output
-    #   @return [String] the final answer text
-    # @!attribute [r] confidence
-    #   @return [Float] combined confidence score (0.0–1.0)
-    # @!attribute [r] citations
-    #   @return [Array<Hash>] [{source:, excerpt:}, ...]
-    #
-    #   **WARNING**: These citations are extracted from the LLM's own response
-    #   and are **not** verified against any external knowledge base or URL.
-    #   Do not treat them as authoritative without independent verification.
-    # @!attribute [r] iterations
-    #   @return [Integer] number of draft-review cycles executed
-    # @!attribute [r] review_notes
-    #   @return [Array<String>] reviewer feedback for each cycle
-    # @!attribute [r] trusted
-    #   @return [Boolean] true when confidence >= threshold
     Result = Struct.new(
-      :output, :confidence, :citations, :iterations, :review_notes, :trusted
+      :output,
+      :confidence,
+      :citations,
+      :iterations,
+      :review_notes,
+      :trusted
     ) do
-      # @return [Boolean] true when confidence >= threshold
       alias_method :trusted?, :trusted
     end
 
-    # Internal graph state — not part of the public API.
-    # @private
     class PipelineState
       include Phronomy::WorkflowContext
 
       field :input, type: :replace, default: -> { "" }
-      field :draft, type: :replace, default: -> {}
+      field :draft, type: :replace, default: -> { {} }
       field :self_score, type: :replace, default: -> { 0.0 }
       field :review_score, type: :replace, default: -> { 0.0 }
       field :citations, type: :replace, default: -> { [] }
       field :review_notes, type: :append, default: -> { [] }
       field :iteration, type: :replace, default: -> { 0 }
       field :approved, type: :replace, default: -> { false }
-      field :output, type: :replace, default: -> {}
+      field :output, type: :replace, default: -> { {} }
+      field :draft_request_id, type: :replace, default: nil
+      field :review_request_id, type: :replace, default: nil
+      field :pipeline_error, type: :replace, default: nil
+
+      # Application-level event interpretation. Correlation IDs belong to this
+      # Pipeline rather than to the generic FSMSession.
+      def handle_fsm_event(event)
+        case event.type
+        when :draft_completed
+          return :consume unless event.payload[:request_id] == draft_request_id
+
+          self.draft = event.payload[:draft]
+          self.self_score = event.payload[:self_score]
+          self.citations = event.payload[:citations]
+          self.iteration = iteration + 1
+          self.draft_request_id = nil
+          self.pipeline_error = nil
+        when :review_completed
+          return :consume unless event.payload[:request_id] == review_request_id
+
+          self.review_score = event.payload[:review_score]
+          self.approved = event.payload[:approved]
+          self.review_notes = review_notes + [event.payload[:feedback]]
+          self.review_request_id = nil
+          self.pipeline_error = nil
+        when :draft_failed
+          return :consume unless event.payload[:request_id] == draft_request_id
+
+          self.pipeline_error = event.payload[:error]
+          self.draft_request_id = nil
+        when :review_failed
+          return :consume unless event.payload[:request_id] == review_request_id
+
+          self.pipeline_error = event.payload[:error]
+          self.review_request_id = nil
+        end
+        false
+      end
     end
 
     private_constant :PipelineState
 
-    # @param draft_agent           [Class]   subclass of Phronomy::Agent::Base
-    #   used to generate answer drafts
-    # @param review_agent          [Class]   subclass of Phronomy::Agent::Base
-    #   used to evaluate each draft
-    # @param draft_prompt_builder  [#call]   +call(input, feedback)+ → String
-    #   prompt for the generator. +feedback+ is nil on the first iteration and
-    #   contains the reviewer's feedback string on subsequent iterations.
-    # @param review_prompt_builder [#call]   +call(input, draft, citations)+ → String
-    #   prompt for the verifier. +citations+ is an Array of Hashes.
-    # @param draft_result_parser   [#call, nil]  +call(text)+ → Hash with
-    #   +:answer+, +:confidence+, and +:citations+ keys. Defaults to JSON parsing
-    #   with a safe fallback when the response cannot be parsed.
-    # @param review_result_parser  [#call, nil]  +call(text)+ → Hash with
-    #   +:approved+, +:score+, and +:feedback+ keys. Defaults to JSON parsing
-    #   with a safe fallback.
-    # @param confidence_threshold  [Float]   minimum combined confidence to
-    #   trust an answer (default: 0.7)
-    # @param max_iterations        [Integer] maximum draft-review cycles
-    #   before returning the best-effort answer (default: 3)
-    # @param raise_if_untrusted    [Boolean] when +true+, raises
-    #   {Phronomy::LowConfidenceError} if the final result does not meet the
-    #   confidence threshold (default: false)
-    # @api private
     def initialize(
       draft_agent:,
       review_agent:,
@@ -128,25 +91,18 @@ module Phronomy
       @review_agent_class = review_agent
       @draft_prompt_builder = draft_prompt_builder
       @review_prompt_builder = review_prompt_builder
-      @draft_result_parser = draft_result_parser || method(:default_parse_draft)
-      @review_result_parser = review_result_parser || method(:default_parse_review)
+      @draft_result_parser =
+        draft_result_parser || method(:default_parse_draft)
+      @review_result_parser =
+        review_result_parser || method(:default_parse_review)
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
       @raise_if_untrusted = raise_if_untrusted
       @compiled_workflow = nil
     end
 
-    # Run the generator-verifier pipeline.
-    #
-    # @param input  [String] the user question or task description
-    # @param config [Hash]   forwarded to the underlying agents (e.g. thread_id)
-    # @return [Result]
-    # @raise [Phronomy::LowConfidenceError] when +raise_if_untrusted:+ is +true+
-    #   and the result does not meet the confidence threshold
-    # @api private
     def invoke(input, config: {})
-      app = compiled_workflow
-      state = app.invoke({input: input}, config: config)
+      state = compiled_workflow.invoke({input: input}, config: config)
       confidence = combined_confidence(state)
       trusted = confidence >= @threshold
       result = Result.new(
@@ -157,14 +113,19 @@ module Phronomy
         review_notes: state.review_notes,
         trusted: trusted
       )
-      raise LowConfidenceError.new(result) if @raise_if_untrusted && !trusted
+      if @raise_if_untrusted && !trusted
+        raise LowConfidenceError.new(result)
+      end
       result
     end
 
     private
 
     def combined_confidence(state)
-      [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
+      [
+        (state.self_score || 0.0).to_f,
+        (state.review_score || 0.0).to_f
+      ].min
     end
 
     def compiled_workflow
@@ -175,86 +136,236 @@ module Phronomy
       draft_agent = @draft_agent_class.new
       review_agent = @review_agent_class.new
       threshold = @threshold
-      max_iter = @max_iterations
-      dpb = @draft_prompt_builder
-      rpb = @review_prompt_builder
-      drp = @draft_result_parser
-      rrp = @review_result_parser
+      max_iterations = @max_iterations
+      draft_prompt_builder = @draft_prompt_builder
+      review_prompt_builder = @review_prompt_builder
+      draft_result_parser = @draft_result_parser
+      review_result_parser = @review_result_parser
       pipeline = self
+      workflow = nil
 
-      Phronomy::Workflow.define(PipelineState) do
+      # workflow is assigned after define so closures captured by reference see the result.
+      workflow = Phronomy::Workflow.define(PipelineState) do
         initial :draft
 
         state :draft
         state :review
         state :finalize
+        state :failed
 
         entry :draft, ->(state) {
-          feedback = state.review_notes.last
-          prompt = dpb.call(state.input, feedback)
-          # Return a Task so WorkflowRunner awaits it off the EventLoop thread,
-          # then posts :action_completed with the new context back to EventLoop.
-          draft_agent.invoke_async(prompt).map do |result|
-            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
-            )
-          end
+          request_id = SecureRandom.uuid
+          next_state = state.merge(draft_request_id: request_id)
+          feedback = next_state.review_notes.last
+          prompt = draft_prompt_builder.call(next_state.input, feedback)
+
+          draft_agent.invoke_async(
+            prompt,
+            on_event: ->(agent_event) {
+              case agent_event.type
+              when :done
+                begin
+                  parsed = draft_result_parser.call(
+                    agent_event.payload[:output]
+                  )
+                  workflow.signal(
+                    thread_id: next_state.thread_id,
+                    event: :draft_completed,
+                    payload: {
+                      request_id: request_id,
+                      draft: parsed[:answer].to_s,
+                      self_score: pipeline.__send__(
+                        :clamp,
+                        parsed[:confidence]
+                      ),
+                      citations: pipeline.__send__(
+                        :normalize_citations,
+                        parsed[:citations]
+                      )
+                    }
+                  )
+                rescue => error
+                  workflow.signal(
+                    thread_id: next_state.thread_id,
+                    event: :draft_failed,
+                    payload: {
+                      request_id: request_id,
+                      error: error
+                    }
+                  )
+                end
+              when :error, :timeout, :cancelled
+                workflow.signal(
+                  thread_id: next_state.thread_id,
+                  event: :draft_failed,
+                  payload: {
+                    request_id: request_id,
+                    error:
+                      agent_event.payload[:error] ||
+                      Phronomy::Error.new(
+                        "Draft Agent ended with #{agent_event.type}"
+                      )
+                  }
+                )
+              when :approval_required
+                workflow.signal(
+                  thread_id: next_state.thread_id,
+                  event: :draft_failed,
+                  payload: {
+                    request_id: request_id,
+                    error: Phronomy::Error.new(
+                      "GeneratorVerifier draft Agent suspended for approval"
+                    )
+                  }
+                )
+              end
+            }
+          )
+
+          next_state
         }
 
         entry :review, ->(state) {
-          prompt = rpb.call(state.input, state.draft, state.citations)
-          # Return a Task so WorkflowRunner awaits it off the EventLoop thread.
-          review_agent.invoke_async(prompt).map do |result|
-            parsed = rrp.call(result[:output])
-            state.merge(
-              review_score: pipeline.__send__(:clamp, parsed[:score]),
-              approved: parsed[:approved] == true,
-              review_notes: [parsed[:feedback].to_s]
-            )
-          end
+          request_id = SecureRandom.uuid
+          next_state = state.merge(review_request_id: request_id)
+          prompt = review_prompt_builder.call(
+            next_state.input,
+            next_state.draft,
+            next_state.citations
+          )
+
+          review_agent.invoke_async(
+            prompt,
+            on_event: ->(agent_event) {
+              case agent_event.type
+              when :done
+                begin
+                  parsed = review_result_parser.call(
+                    agent_event.payload[:output]
+                  )
+                  workflow.signal(
+                    thread_id: next_state.thread_id,
+                    event: :review_completed,
+                    payload: {
+                      request_id: request_id,
+                      review_score: pipeline.__send__(
+                        :clamp,
+                        parsed[:score]
+                      ),
+                      approved: parsed[:approved] == true,
+                      feedback: parsed[:feedback].to_s
+                    }
+                  )
+                rescue => error
+                  workflow.signal(
+                    thread_id: next_state.thread_id,
+                    event: :review_failed,
+                    payload: {
+                      request_id: request_id,
+                      error: error
+                    }
+                  )
+                end
+              when :error, :timeout, :cancelled
+                workflow.signal(
+                  thread_id: next_state.thread_id,
+                  event: :review_failed,
+                  payload: {
+                    request_id: request_id,
+                    error:
+                      agent_event.payload[:error] ||
+                      Phronomy::Error.new(
+                        "Review Agent ended with #{agent_event.type}"
+                      )
+                  }
+                )
+              when :approval_required
+                workflow.signal(
+                  thread_id: next_state.thread_id,
+                  event: :review_failed,
+                  payload: {
+                    request_id: request_id,
+                    error: Phronomy::Error.new(
+                      "GeneratorVerifier review Agent suspended for approval"
+                    )
+                  }
+                )
+              end
+            }
+          )
+
+          next_state
         }
 
-        entry :finalize, ->(state) { state.output = state.draft }
+        entry :finalize, ->(state) {
+          state.output = state.draft
+          state
+        }
 
-        transition from: :draft, to: :review
-        transition from: :finalize, to: :__finish__
+        entry :failed, ->(state) {
+          raise(
+            state.pipeline_error ||
+            Phronomy::Error.new("GeneratorVerifier Agent operation failed")
+          )
+        }
+
+        transition from: :draft, on: :draft_completed, to: :review
+        transition from: :draft, on: :draft_failed, to: :failed
 
         transition from: :review,
+          on: :review_completed,
           guard: ->(state) {
-            confidence = [state.self_score || 0.0, state.review_score || 0.0].min
-            (confidence >= threshold && state.approved) || state.iteration >= max_iter
+            confidence = [
+              state.self_score || 0.0,
+              state.review_score || 0.0
+            ].min
+            (confidence >= threshold && state.approved) ||
+              state.iteration >= max_iterations
           },
           to: :finalize
-        transition from: :review, to: :draft
+        transition from: :review,
+          on: :review_completed,
+          to: :draft
+        transition from: :review,
+          on: :review_failed,
+          to: :failed
+
+        transition from: :finalize, to: :__finish__
       end
     end
 
     def default_parse_draft(text)
       json_parser.parse(text)
     rescue Phronomy::ParseError
-      {answer: text.to_s, confidence: 0.0, citations: []}
+      {
+        answer: text.to_s,
+        confidence: 0.0,
+        citations: []
+      }
     end
 
     def default_parse_review(text)
       json_parser.parse(text)
     rescue Phronomy::ParseError
-      {approved: false, score: 0.0, feedback: "Review output could not be parsed: #{text}"}
+      {
+        approved: false,
+        score: 0.0,
+        feedback: "Review output could not be parsed: #{text}"
+      }
     end
 
     def json_parser
       @json_parser ||= Phronomy::OutputParser::JsonParser.new
     end
 
-    def clamp(val)
-      val.to_f.clamp(0.0, 1.0)
+    def clamp(value)
+      value.to_f.clamp(0.0, 1.0)
     end
 
     def normalize_citations(raw)
-      Array(raw).filter_map { |c| c.is_a?(Hash) ? c.transform_keys(&:to_sym) : nil }
+      Array(raw).filter_map do |citation|
+        citation.is_a?(Hash) ? citation.transform_keys(&:to_sym) : nil
+      end
     end
   end
 end

data/lib/phronomy/invalid_async_entry_action_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Raised when a synchronous FSM entry action returns Phronomy::Task.
+  #
+  # Entry actions are Run-to-Completion callbacks. They may start asynchronous
+  # work, but completion must return through a later explicit event.
+  class InvalidAsyncEntryActionError < InvalidAsyncWorkflowActionError; end
+end

data/lib/phronomy/invalid_async_transition_action_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Raised when a synchronous Workflow transition action returns Phronomy::Task.
+  #
+  # Transition actions are Run-to-Completion callbacks. They may start
+  # asynchronous work, but completion must return through a later explicit event.
+  class InvalidAsyncTransitionActionError <
+    InvalidAsyncWorkflowActionError
+  end
+end

data/lib/phronomy/invalid_async_workflow_action_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Base error for synchronous Workflow callbacks that return Phronomy::Task.
+  #
+  # Workflow callbacks may start asynchronous work, but they must return
+  # synchronously and deliver completion through a later explicit event.
+  class InvalidAsyncWorkflowActionError < Error; end
+end

data/lib/phronomy/invocation_context.rb

@@ -10,9 +10,8 @@ module Phronomy
   #
   # @example Build a context for a new agent invocation
   #   ctx = Phronomy::InvocationContext.new(
-  #     thread_id:         "conv-123",
-  #     cancellation_token: Phronomy::Concurrency::CancellationToken.timeout_after(30),
-  #     max_parallel_tools: 5
+  #     thread_id: "conv-123",
+  #     cancellation_token: Phronomy::Concurrency::CancellationToken.timeout_after(30)
   #   )
   #   agent.invoke("Hello", invocation_context: ctx)
   class InvocationContext
@@ -37,18 +36,13 @@ module Phronomy
     # @return [Integer, nil] max tokens the agent may consume this invocation
     attr_reader :token_budget
 
-    # @return [Integer] maximum simultaneous tool calls (default: 10)
-    attr_reader :max_parallel_tools
-
-    # @return [Object, nil] approval policy applied before write-scope tools
+    # @return [#call, nil] invocation-specific Tool approval policy. The callable
+    #   receives Phronomy::Agent::ApprovalEvaluationRequest.
     attr_reader :approval_policy
 
     # @return [Object, nil] redaction policy applied to tool args / results
     attr_reader :redaction_policy
 
-    # @return [Hash, nil] per-provider concurrency / rate-limit overrides
-    attr_reader :provider_limits
-
     # @return [String, nil] unique identifier for this task in the trace tree
     attr_reader :task_id
 
@@ -62,10 +56,8 @@ module Phronomy
     # @param deadline [Deadline, nil]
     # @param tracer_span [Object, nil]
     # @param token_budget [Integer, nil]
-    # @param max_parallel_tools [Integer]
-    # @param approval_policy [Object, nil]
+    # @param approval_policy [#call, nil] invocation-specific Tool approval policy
     # @param redaction_policy [Object, nil]
-    # @param provider_limits [Hash, nil]
     # @param task_id [String, nil]
     # @param parent_task_id [String, nil]
     # @api private
@@ -77,10 +69,8 @@ module Phronomy
       deadline: nil,
       tracer_span: nil,
       token_budget: nil,
-      max_parallel_tools: 10,
       approval_policy: nil,
       redaction_policy: nil,
-      provider_limits: nil,
       task_id: nil,
       parent_task_id: nil
     )
@@ -91,10 +81,8 @@ module Phronomy
       @deadline = deadline
       @tracer_span = tracer_span
       @token_budget = token_budget
-      @max_parallel_tools = max_parallel_tools
       @approval_policy = approval_policy
       @redaction_policy = redaction_policy
-      @provider_limits = provider_limits
       @task_id = task_id
       @parent_task_id = parent_task_id
     end
@@ -114,10 +102,8 @@ module Phronomy
         deadline: overrides.fetch(:deadline, @deadline),
         tracer_span: overrides.fetch(:tracer_span, @tracer_span),
         token_budget: overrides.fetch(:token_budget, @token_budget),
-        max_parallel_tools: overrides.fetch(:max_parallel_tools, @max_parallel_tools),
         approval_policy: overrides.fetch(:approval_policy, @approval_policy),
         redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
-        provider_limits: overrides.fetch(:provider_limits, @provider_limits),
         task_id: overrides.fetch(:task_id, @task_id),
         parent_task_id: overrides.fetch(:parent_task_id, @parent_task_id)
       )