phronomy 0.28.0 → 0.30.0

data/lib/phronomy/generation/generator_verifier/protocol.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Generation defines the information it needs. Agent owns schema validation.
+    # @api private
+    module Protocol
+      DEFAULT_CITATION = Phronomy::Values::Immutable.json({
+        type: "object", properties: {source: {type: "string"}, excerpt: {type: "string"}},
+        required: %w[source excerpt], additionalProperties: false
+      })
+      REVIEW = Phronomy::Values::Immutable.json({
+        type: "object", properties: {approved: {type: "boolean"}, score: {type: "number", minimum: 0, maximum: 1},
+                                     feedback: {type: "string"}},
+        required: %w[approved score feedback], additionalProperties: false
+      })
+
+      module_function
+
+      def draft(citation_schema)
+        citation = Phronomy::Values::Immutable.json(citation_schema)
+        unless citation.is_a?(Hash) && citation["type"] == "object"
+          raise ArgumentError, "citation_schema must declare an object"
+        end
+        Phronomy::Values::Immutable.json({
+          type: "object", properties: {answer: {type: "string"}, confidence: {type: "number", minimum: 0, maximum: 1},
+                                       citations: {type: "array", items: embed_citation(citation)}},
+          required: %w[answer confidence citations], additionalProperties: false
+        })
+      end
+
+      # A local citation reference is relative to the citation document. Rebase
+      # only schema positions when embedding it, leaving const/enum data intact.
+      def embed_citation(node)
+        return node unless node.is_a?(Hash)
+        node.to_h do |key, value|
+          transformed = case key
+          when "$ref"
+            (value.is_a?(String) && value.start_with?("#")) ? "#/properties/citations/items#{value.delete_prefix("#")}" : value
+          when "properties", "$defs"
+            value.is_a?(Hash) ? value.transform_values { |child| embed_citation(child) } : value
+          when "items", "additionalProperties"
+            embed_citation(value)
+          when "anyOf"
+            value.is_a?(Array) ? value.map { |child| embed_citation(child) } : value
+          else
+            value
+          end
+          [key, transformed]
+        end
+      end
+      private_class_method :embed_citation
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/result.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Immutable, JSON-reconstructible facts about one generation attempt.
+    # Acceptance is the configured evaluation outcome, not application publication.
+    class Result
+      FIELDS = %i[output confidence citations iterations review_notes
+        confidence_threshold review_approved termination_reason interrupted_phase failure].freeze
+      attr_reader(*FIELDS)
+
+      def self.accepted?(confidence:, confidence_threshold:, review_approved:)
+        review_approved == true && !confidence.nil? && confidence >= confidence_threshold
+      end
+
+      def self.from_h(hash)
+        raise ArgumentError, "Result data must be a Hash" unless hash.is_a?(Hash)
+        fields = hash.each_with_object({}) do |(key, value), result|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise ArgumentError, "Result keys must be String or Symbol"
+          end
+          key = key.to_sym
+          raise ArgumentError, "duplicate Result field: #{key}" if result.key?(key)
+          result[key] = value
+        end
+        raise ArgumentError, "unknown Result fields" unless (fields.keys - FIELDS).empty?
+        raise ArgumentError, "missing Result fields" unless (FIELDS - fields.keys).empty?
+        new(**fields)
+      end
+
+      def initialize(output:, confidence:, citations:, iterations:, review_notes:,
+        confidence_threshold:, review_approved:, termination_reason:, interrupted_phase: nil, failure: nil)
+        @output = output&.dup&.freeze
+        @confidence = score(confidence, optional: true)
+        @confidence_threshold = score(confidence_threshold)
+        @review_approved = review_approved
+        @termination_reason = termination_reason.to_s.freeze
+        @interrupted_phase = interrupted_phase&.to_s&.freeze
+        @failure = Phronomy::Values::Immutable.json(failure)
+        @iterations = iterations
+        @citations = Phronomy::Values::Immutable.json(citations)
+        @review_notes = Phronomy::Values::Immutable.copy(review_notes)
+        validate!
+        freeze
+      end
+
+      def accepted?
+        @termination_reason == "accepted"
+      end
+
+      def to_h
+        FIELDS.to_h { |field| [field, public_send(field)] }
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && to_h == other.to_h
+      end
+      alias_method :eql?, :==
+
+      def hash
+        [self.class, to_h].hash
+      end
+
+      private
+
+      def score(value, optional: false)
+        return nil if optional && value.nil?
+        unless value.is_a?(Numeric) && value.real? && value.to_f.finite? && (0.0..1.0).cover?(value)
+          raise ArgumentError, "scores and threshold must be finite numbers in 0..1"
+        end
+        value.to_f
+      end
+
+      def validate!
+        unless @output.nil? || @output.is_a?(String)
+          raise ArgumentError, "output must be a String or nil"
+        end
+        unless @iterations.is_a?(Integer) && @iterations >= 0
+          raise ArgumentError, "iterations must be a nonnegative Integer"
+        end
+        unless @citations.is_a?(Array) && @citations.all?(Hash) &&
+            @review_notes.is_a?(Array) && @review_notes.all?(String)
+          raise ArgumentError, "citations must be hashes and review_notes must be strings"
+        end
+        if @termination_reason == "output_failed"
+          unless @failure.is_a?(Hash) && %w[agent.output_invalid agent.output_refused agent.output_incomplete].include?(@failure["code"]) &&
+              %w[reason execution_id schema_digest].all? { |key| @failure[key].is_a?(String) && !@failure[key].empty? } &&
+              @failure["violations"].is_a?(Array) && @failure["class"] == "Phronomy::Agent::OutputError"
+            raise ArgumentError, "output failure requires a complete Agent output diagnostic"
+          end
+          reasons = {"agent.output_invalid" => %w[invalid_json schema_mismatch missing_output],
+                     "agent.output_refused" => %w[model_refusal],
+                     "agent.output_incomplete" => %w[length content_filter unknown_finish_reason]}
+          unless reasons.fetch(@failure.fetch("code")).include?(@failure.fetch("reason"))
+            raise ArgumentError, "output failure reason contradicts its code"
+          end
+          if @interrupted_phase == "draft"
+            raise ArgumentError, "failed draft cannot carry an earlier answer" unless @output.nil? && @citations.empty?
+          elsif @interrupted_phase == "review"
+            raise ArgumentError, "failed review requires a valid draft" unless @output.is_a?(String) && @iterations.positive?
+          end
+        elsif @failure
+          raise ArgumentError, "only output_failed may carry failure"
+        end
+        if %w[tool_rejected output_failed].include?(@termination_reason)
+          unless %w[draft review].include?(@interrupted_phase) && @review_approved.nil? && @confidence.nil?
+            raise ArgumentError, "interruption must identify its phase and has no completed evaluation"
+          end
+          return
+        end
+        unless @iterations.positive? && @output.is_a?(String) && !@confidence.nil? &&
+            [true, false].include?(@review_approved) && @interrupted_phase.nil?
+          raise ArgumentError, "completed evaluation requires output, score and boolean review_approved"
+        end
+        expected = self.class.accepted?(confidence: @confidence,
+          confidence_threshold: @confidence_threshold, review_approved: @review_approved) ? "accepted" : "iteration_limit"
+        raise ArgumentError, "termination_reason contradicts evaluation" unless @termination_reason == expected
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/unaccepted_result_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    class UnacceptedResultError < Phronomy::Error
+      attr_reader :result
+
+      def initialize(result, code: "generation.result_unaccepted")
+        @result = result
+        super("Generation did not satisfy its evaluation conditions (#{result.termination_reason})", code: code)
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/workflow_builder.rb

@@ -9,19 +9,16 @@ module Phronomy
       def initialize(
         draft_agent:, review_agent:,
         draft_prompt_builder:, review_prompt_builder:,
-        draft_result_parser:, review_result_parser:,
-        threshold:, max_iterations:
+        threshold:, max_iterations:, start_operation:
       )
+        @start_operation = start_operation
         @draft_agent = draft_agent
         @review_agent = review_agent
         @draft_prompt_builder = draft_prompt_builder
         @review_prompt_builder = review_prompt_builder
         @threshold = threshold
         @max_iterations = max_iterations
-        @result_receiver = AgentResultReceiver.new(
-          draft_result_parser: draft_result_parser,
-          review_result_parser: review_result_parser
-        )
+        @result_receiver = AgentResultReceiver.new
       end
 
       def build
@@ -48,6 +45,10 @@ module Phronomy
 
           transition from: :draft, on: :draft_completed, to: :review
           transition from: :draft, on: :draft_failed, to: :failed
+          transition from: :draft, on: :draft_output_failed, to: :finalize
+          transition from: :review, on: :review_output_failed, to: :finalize
+          transition from: :draft, on: :draft_rejected, to: :finalize
+          transition from: :review, on: :review_rejected, to: :finalize
           transition from: :review,
             on: :review_completed,
             guard: ready_to_finalize,
@@ -71,7 +72,7 @@ module Phronomy
           workflow_instance_id: next_state.workflow_instance_id,
           request_id: request_id
         )
-        @draft_agent.start(prompt, listener: listener)
+        @start_operation.call(@draft_agent, :draft, prompt, listener: listener)
         next_state
       end
 
@@ -86,18 +87,19 @@ module Phronomy
           workflow_instance_id: next_state.workflow_instance_id,
           request_id: request_id
         )
-        @review_agent.start(prompt, listener: listener)
+        @start_operation.call(@review_agent, :review, prompt, listener: listener)
         next_state
       end
 
       def ready_to_finalize?(state)
-        confidence = [state.self_score || 0.0, state.review_score || 0.0].min
-        (confidence >= @threshold && state.approved) ||
+        confidence = [state.self_score, state.review_score].min
+        Result.accepted?(confidence: confidence, confidence_threshold: @threshold, review_approved: state.approved) ||
           state.iteration >= @max_iterations
       end
 
       def finalize(state)
-        state.output = state.draft
+        state.output = (state.interrupted_phase == :draft) ? nil : state.draft
+        state.citations = [] if state.interrupted_phase == :draft
         state
       end
 

data/lib/phronomy/generation/generator_verifier.rb

@@ -1,118 +1,203 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Implements the Generator-Verifier multi-agent coordination pattern.
-  #
-  # Agent completion is integrated through application-defined Workflow events;
-  # Workflow entry actions do not return or await Agent Tasks.
+  # Application-facing draft/review/retry composition.
+  # Owns its Agent instances; Tool authorization remains an application decision.
   class GeneratorVerifier
     DEFAULT_CONFIDENCE_THRESHOLD = 0.7
     DEFAULT_MAX_ITERATIONS = 3
 
-    Result = Struct.new(
-      :output,
-      :confidence,
-      :citations,
-      :iterations,
-      :review_notes,
-      :trusted
-    ) do
-      alias_method :trusted?, :trusted
-    end
+    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver,
+      :AgentOperation, :Invocation, :Protocol
 
-    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver, :AgentOperation
+    def self.open(**options)
+      raise ArgumentError, "GeneratorVerifier.open requires a block" unless block_given?
+      pipeline = new(**options)
+      value = nil
+      primary = nil
+      begin
+        returned = yield pipeline
+        value = returned.is_a?(Phronomy::TaskResult) ? returned.wait_result : returned
+      rescue Exception => error # rubocop:disable Lint/RescueException -- retain Interrupt during cleanup
+        primary = error
+        raise
+      ensure
+        begin
+          pipeline.release!
+        rescue => cleanup
+          failures = cleanup.is_a?(CleanupError) ? cleanup.failures : [{phase: nil, error: cleanup}]
+          raise CleanupError.new(pipeline: pipeline, failures: failures,
+            result: value, primary_error: primary), cause: primary || failures.first.fetch(:error)
+        end
+      end
+      value
+    end
 
-    def initialize(
-      draft_agent:,
-      review_agent:,
-      draft_prompt_builder:,
-      review_prompt_builder:,
-      draft_result_parser: nil,
-      review_result_parser: nil,
+    def initialize(draft_agent:, review_agent:, draft_prompt_builder:, review_prompt_builder:,
+      citation_schema: Protocol::DEFAULT_CITATION,
       confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
-      max_iterations: DEFAULT_MAX_ITERATIONS,
-      raise_if_untrusted: false
-    )
-      @draft_agent_class = draft_agent
-      @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)
+      max_iterations: DEFAULT_MAX_ITERATIONS, raise_if_unaccepted: false, on_approval: nil)
+      ensure_blocking_allowed!(:new)
+      unless confidence_threshold.is_a?(Numeric) && confidence_threshold.real? && confidence_threshold.to_f.finite? &&
+          (0.0..1.0).cover?(confidence_threshold)
+        raise ArgumentError, "confidence_threshold must be a finite number in 0..1"
+      end
+      unless max_iterations.is_a?(Integer) && max_iterations.positive?
+        raise ArgumentError, "max_iterations must be a positive Integer"
+      end
+      [draft_prompt_builder, review_prompt_builder, on_approval].compact.each do |callable|
+        raise ArgumentError, "builders and on_approval must be callable" unless callable.respond_to?(:call)
+      end
+      unless raise_if_unaccepted == true || raise_if_unaccepted == false
+        raise ArgumentError, "raise_if_unaccepted must be true or false"
+      end
+      @mutex = Mutex.new
+      @status = :idle
+      @operations = {}
+      @active = nil
       @threshold = confidence_threshold.to_f
-      @max_iterations = max_iterations.to_i
-      @raise_if_untrusted = raise_if_untrusted
-      @compiled_workflow = nil
+      @max_iterations = max_iterations
+      @raise_if_unaccepted = raise_if_unaccepted
+      @on_approval = on_approval
+      @draft_prompt_builder, @review_prompt_builder = draft_prompt_builder, review_prompt_builder
+      draft_schema = Protocol.draft(citation_schema)
+      begin
+        @operations[:draft] = AgentOperation.new(draft_agent, output_schema: draft_schema)
+        @operations[:review] = AgentOperation.new(review_agent, output_schema: Protocol::REVIEW)
+      rescue Exception => primary # rubocop:disable Lint/RescueException -- release partially acquired resources
+        begin
+          release!
+        rescue CleanupError => cleanup
+          raise CleanupError.new(pipeline: self, failures: cleanup.failures,
+            primary_error: primary), cause: primary
+        end
+        raise
+      end
     end
 
     def invoke(input, config: {})
-      state = compiled_workflow.invoke({input: input}, config: config)
-      confidence = combined_confidence(state)
-      trusted = confidence >= @threshold
-      result = Result.new(
-        output: state.output || state.draft.to_s,
-        confidence: confidence,
-        citations: state.citations,
-        iterations: state.iteration,
-        review_notes: state.review_notes,
-        trusted: trusted
-      )
-      if @raise_if_untrusted && !trusted
-        raise LowConfidenceError.new(result)
+      ensure_blocking_allowed!(:invoke)
+      invoke_async(input, config: config).wait_result
+    end
+
+    def invoke_async(input, config: {})
+      invocation = @mutex.synchronize do
+        assert_idle!
+        current = Invocation.new(config: config, on_approval: @on_approval,
+          on_finish: -> { @mutex.synchronize { @active = nil } })
+        @active = current
       end
-      result
+      invocation.follow(compiled_workflow.invoke_async({input: input}, config: invocation.config)) do |state|
+        build_result(state)
+      end
+    rescue => error
+      invocation ? invocation.fail_start(error) : Phronomy::TaskResult.failed(error)
+    end
+
+    # Notifications issued in the current invocation, including already-answered
+    # requests. This is not a replica of the Agent's durable approval state.
+    def approval_requests
+      @mutex.synchronize { @active }&.approvals || [].freeze
+    end
+
+    # Requests cancellation; this Task does not promise physical quiescence.
+    # Await the invocation separately, then use release! to check safe release.
+    def cancel_async
+      current, operations = @mutex.synchronize do
+        if @status == :releasing
+          raise Phronomy::Error.new("Generation is releasing", code: "generation.busy")
+        end
+        [@active, @operations.values.dup]
+      end
+      current&.cancel
+      tasks = operations.filter_map(&:cancel_async)
+      Phronomy::TaskResult.all_settled(tasks).map do |outcomes|
+        failure = outcomes.find(&:error)
+        raise failure.error if failure
+        !!current || !tasks.empty?
+      end
+    rescue => error
+      Phronomy::TaskResult.failed(error)
+    end
+
+    def release!
+      ensure_blocking_allowed!(:release!)
+      operations = @mutex.synchronize do
+        return false if @status == :released
+        if @active || @status == :releasing
+          raise Phronomy::Error.new("Generation is busy", code: "generation.busy")
+        end
+        @status = :releasing
+        @operations.dup
+      end
+      failures = []
+      operations.each do |phase, operation|
+        operation.unload!
+        @mutex.synchronize { @operations.delete(phase) }
+      rescue => error
+        failures << {phase: phase, error: error}
+      end
+      @mutex.synchronize { @status = failures.empty? ? :released : :release_failed }
+      unless failures.empty?
+        raise CleanupError.new(pipeline: self, failures: failures), cause: failures.first.fetch(:error)
+      end
+      @compiled_workflow = nil
+      true
     end
 
     private
 
-    def combined_confidence(state)
-      [
-        (state.self_score || 0.0).to_f,
-        (state.review_score || 0.0).to_f
-      ].min
+    def assert_idle!
+      if @status != :idle
+        raise Phronomy::Error.new("Generation is #{@status}", code: "generation.released")
+      end
+      raise Phronomy::Error.new("Generation is busy", code: "generation.busy") if @active
     end
 
-    def compiled_workflow
-      @compiled_workflow ||= build_workflow
+    def ensure_blocking_allowed!(operation)
+      if Phronomy::WaitPolicy.blocking_forbidden?
+        raise Phronomy::EventLoopReentrancyError, "GeneratorVerifier##{operation} cannot run on EventLoop"
+      end
     end
 
-    def build_workflow
-      WorkflowBuilder.new(
-        draft_agent: AgentOperation.new(@draft_agent_class),
-        review_agent: AgentOperation.new(@review_agent_class),
+    def compiled_workflow
+      @compiled_workflow ||= WorkflowBuilder.new(
+        draft_agent: @operations.fetch(:draft),
+        review_agent: @operations.fetch(:review),
         draft_prompt_builder: @draft_prompt_builder,
         review_prompt_builder: @review_prompt_builder,
-        draft_result_parser: @draft_result_parser,
-        review_result_parser: @review_result_parser,
-        threshold: @threshold,
-        max_iterations: @max_iterations
+        threshold: @threshold, max_iterations: @max_iterations,
+        start_operation: ->(operation, phase, input, listener:) {
+          @mutex.synchronize { @active }.start(operation, phase, input, listener: listener)
+        }
       ).build
     end
 
-    def default_parse_draft(text)
-      default_parser.parse(text)
-    rescue Phronomy::ParseError
-      {
-        answer: text.to_s,
-        confidence: 0.0,
-        citations: []
-      }
-    end
-
-    def default_parse_review(text)
-      default_parser.parse(text)
-    rescue Phronomy::ParseError
-      {
-        approved: false,
-        score: 0.0,
-        feedback: "Review output could not be parsed: #{text}"
-      }
+    def build_result(state)
+      interrupted = state.interrupted_phase
+      confidence = interrupted ? nil : [state.self_score, state.review_score].min
+      approved = interrupted ? nil : state.approved
+      accepted = Result.accepted?(confidence: confidence, confidence_threshold: @threshold, review_approved: approved)
+      result = Result.new(output: state.output, confidence: confidence,
+        confidence_threshold: @threshold, review_approved: approved,
+        citations: state.citations, iterations: state.iteration, review_notes: state.review_notes,
+        termination_reason: if interrupted
+                              state.pipeline_error ? "output_failed" : "tool_rejected"
+                            else
+                              (accepted ? "accepted" : "iteration_limit")
+                            end,
+        interrupted_phase: interrupted,
+        failure: output_failure_diagnostic(state.pipeline_error))
+      if @raise_if_unaccepted && !result.accepted?
+        raise UnacceptedResultError.new(result), cause: state.pipeline_error
+      end
+      result
     end
 
-    def default_parser
-      @default_parser ||= DefaultParser.build
+    def output_failure_diagnostic(error)
+      return nil unless error
+      Phronomy::Error.diagnostic(error).merge("execution_id" => error.execution_id,
+        "schema_digest" => error.schema_digest, "reason" => error.reason, "violations" => error.violations)
     end
   end
 end