phronomy 0.25.0 → 0.27.0

data/lib/phronomy/agent/token_budget_resolver.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Resolves a TokenBudget from the effective model configuration that will
-    # actually be materialized for one LLM call.
-    class TokenBudgetResolver
-      def initialize(agent:)
-        @agent = agent
-      end
-
-      def resolve(model_config)
-        config = stringify_keys(model_config)
-        model_name = config["model"]
-        explicit_window = integer_or_nil(config["context_window"])
-        explicit_reserve = integer_or_nil(config["max_output_tokens"])
-
-        if explicit_window
-          reserve = explicit_reserve || configured_default_reserve
-          return build_budget(explicit_window, reserve, model_name)
-        end
-
-        return nil unless model_name
-
-        model = RubyLLM.models.find(model_name)
-        return nil unless model
-
-        context_window = model.context_window.to_i
-        registry_max = model.max_output_tokens.to_i
-        reserve = explicit_reserve || configured_default_reserve
-        reserve ||= registry_max if registry_max.positive? && registry_max < context_window
-        build_budget(context_window, reserve, model_name)
-      rescue RubyLLM::ModelNotFoundError
-        nil
-      end
-
-      private
-
-      def build_budget(context_window, reserve, model_name)
-        unless reserve&.positive? && reserve < context_window
-          raise Phronomy::InvalidContextBudgetConfigurationError,
-            "Cannot determine a valid output reserve for model #{model_name.inspect}; " \
-            "set max_output_tokens or Phronomy.configuration.default_output_reserve"
-        end
-
-        # Mandatory Manifest content is accounted separately by ContextAssembler
-        # and the final budget validator. TokenBudget reserves output capacity only.
-        Phronomy::LlmContextWindow::TokenBudget.new(
-          context_window: context_window,
-          max_output_tokens: reserve
-        )
-      end
-
-      def configured_default_reserve
-        integer_or_nil(Phronomy.configuration.default_output_reserve)
-      end
-
-      def integer_or_nil(value)
-        return nil if value.nil?
-        Integer(value)
-      end
-
-      def stringify_keys(hash)
-        hash.to_h.each_with_object({}) do |(key, value), result|
-          result[key.to_s] = value
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/tool_executor.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Routes Tool work according to the Tool execution contract.
-    #
-    # Both execution modes return {Phronomy::Task}; only the execution mechanism
-    # differs.
-    #
-    # :cooperative Tool calls execute inline and must return quickly. call_async
-    # wraps their result in an already-settled Task and never consumes an
-    # OffloadPool worker.
-    #
-    # :offloaded Tool calls route synchronous work through OffloadPool, whose
-    # caller-facing completion handle is also a Task. Phronomy does not distinguish
-    # whether the reason is blocking I/O, CPU-bound work, or another long
-    # synchronous operation.
-    module ToolExecutor
-      def self.call_async(
-        tool:,
-        args:,
-        cancellation_token: nil,
-        config: {},
-        runtime: nil,
-        on_full: :raise
-      )
-        mode = tool.class.execution_mode
-
-        case mode
-        when :cooperative
-          task = Phronomy::Task.deferred(name: "tool-#{tool.name}")
-          begin
-            task.complete(
-              tool.call(args, cancellation_token: cancellation_token)
-            )
-          rescue => error
-            task.fail(error)
-          end
-          task
-        when :offloaded
-          runtime ||= Phronomy::Runtime.instance
-          runtime.offload.submit(
-            cancellation_token: cancellation_token,
-            on_full: on_full
-          ) do
-            tool.call(args, cancellation_token: cancellation_token)
-          end
-        else
-          raise Phronomy::ConfigurationError,
-            "unknown Tool execution_mode: #{mode.inspect}"
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/generator_verifier.rb

@@ -1,369 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-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.
-  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
-
-    class PipelineState
-      include Phronomy::WorkflowContext
-
-      field :input, 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 :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
-
-    def initialize(
-      draft_agent:,
-      review_agent:,
-      draft_prompt_builder:,
-      review_prompt_builder:,
-      draft_result_parser: nil,
-      review_result_parser: nil,
-      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)
-      @threshold = confidence_threshold.to_f
-      @max_iterations = max_iterations.to_i
-      @raise_if_untrusted = raise_if_untrusted
-      @compiled_workflow = nil
-    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)
-      end
-      result
-    end
-
-    private
-
-    def combined_confidence(state)
-      [
-        (state.self_score || 0.0).to_f,
-        (state.review_score || 0.0).to_f
-      ].min
-    end
-
-    def compiled_workflow
-      @compiled_workflow ||= build_workflow
-    end
-
-    def build_workflow
-      draft_agent = @draft_agent_class.new
-      review_agent = @review_agent_class.new
-      threshold = @threshold
-      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
-
-      # 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) {
-          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.send(:__invoke_async_with_event_sink,
-            prompt,
-            on_event: ->(agent_event) {
-              case agent_event.type
-              when :done
-                begin
-                  parsed = draft_result_parser.call(
-                    agent_event.payload[:output]
-                  )
-                  workflow.signal(
-                    workflow_instance_id: next_state.workflow_instance_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(
-                    workflow_instance_id: next_state.workflow_instance_id,
-                    event: :draft_failed,
-                    payload: {
-                      request_id: request_id,
-                      error: error
-                    }
-                  )
-                end
-              when :error, :timeout, :cancelled
-                workflow.signal(
-                  workflow_instance_id: next_state.workflow_instance_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(
-                  workflow_instance_id: next_state.workflow_instance_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) {
-          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.send(:__invoke_async_with_event_sink,
-            prompt,
-            on_event: ->(agent_event) {
-              case agent_event.type
-              when :done
-                begin
-                  parsed = review_result_parser.call(
-                    agent_event.payload[:output]
-                  )
-                  workflow.signal(
-                    workflow_instance_id: next_state.workflow_instance_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(
-                    workflow_instance_id: next_state.workflow_instance_id,
-                    event: :review_failed,
-                    payload: {
-                      request_id: request_id,
-                      error: error
-                    }
-                  )
-                end
-              when :error, :timeout, :cancelled
-                workflow.signal(
-                  workflow_instance_id: next_state.workflow_instance_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(
-                  workflow_instance_id: next_state.workflow_instance_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
-          state
-        }
-
-        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_iterations
-          },
-          to: :finalize
-        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: []
-      }
-    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}"
-      }
-    end
-
-    def json_parser
-      @json_parser ||= Phronomy::OutputParser::JsonParser.new
-    end
-
-    def clamp(value)
-      value.to_f.clamp(0.0, 1.0)
-    end
-
-    def normalize_citations(raw)
-      Array(raw).filter_map do |citation|
-        citation.is_a?(Hash) ? citation.transform_keys(&:to_sym) : nil
-      end
-    end
-  end
-end

data/lib/phronomy/invalid_context_budget_configuration_error.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Raised when output token reserve cannot be determined at budget construction
-  # time (e.g. no explicit max_output_tokens set and registry value equals the
-  # context window).
-  class InvalidContextBudgetConfigurationError < Error; end
-end

data/lib/phronomy/multi_agent/fan_out_invocation.rb

@@ -1,137 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module MultiAgent
-    # Mutable FSM context for one fan-out operation.
-    class FanOutInvocation
-      Child = Data.define(:index, :agent, :input, :config)
-
-      attr_reader :phase, :results
-
-      def initialize(children:, max_concurrency:, on_error:)
-        @phase = nil
-        @children = children
-        @max_concurrency = max_concurrency || children.length
-        @on_error = on_error
-        @pending = children.dup
-        @active = {}
-        @results = Array.new(children.length)
-        @child_errors = Array.new(children.length)
-        @fatal_error = nil
-        @cancelled = false
-        @timed_out = false
-      end
-
-      def set_graph_metadata(phase: nil)
-        @phase = phase
-      end
-
-      def handle_fsm_event(event)
-        case event.type
-        when :child_completed
-          payload = event.payload
-          index = payload.fetch(:index)
-          @active.delete(index)
-          child_error = payload[:error]
-          if child_error
-            if @on_error == :raise
-              @child_errors[index] = child_error
-              cancel_active_children! unless @child_errors.any?(&:itself)
-            end
-          else
-            @results[index] = payload[:result]
-          end
-          true
-        when :driver_failed
-          @fatal_error ||= event.payload.fetch(:error)
-          cancel_active_children!
-          true
-        when :timeout
-          @timed_out = true
-          @fatal_error ||= Phronomy::TimeoutError.new(event.payload.fetch(:message))
-          cancel_active_children!
-          true
-        when :cancel
-          @cancelled = true
-          @fatal_error ||= Phronomy::CancellationError.new("fan-out cancelled")
-          cancel_active_children!
-          true
-        else
-          false
-        end
-      end
-
-      def start_available!(runtime, event_sink:)
-        return self if @fatal_error
-
-        while @active.length < @max_concurrency && (child = @pending.shift)
-          child_config = build_child_config(child.config)
-          handle = child.agent.invoke_async(
-            child.input,
-            config: child_config
-          )
-          @active[child.index] = {
-            handle: handle,
-            token: child_config[:cancellation_token]
-          }
-          [child.index].each do |captured_index|
-            handle.on_complete do |result, error|
-              event_sink.post(
-                :child_completed,
-                {
-                  index: captured_index,
-                  result: result,
-                  error: error
-                }
-              )
-            end
-          end
-        end
-        self
-      rescue => caught
-        @fatal_error ||= caught
-        cancel_active_children!
-        event_sink.post(:driver_failed, {error: caught})
-        self
-      end
-
-      def completed?
-        !failed? && @pending.empty? && @active.empty?
-      end
-
-      def failed?
-        return true if @fatal_error
-
-        @on_error == :raise &&
-          @pending.empty? &&
-          @active.empty? &&
-          @child_errors.any?(&:itself)
-      end
-
-      def error
-        @fatal_error || @child_errors.find(&:itself)
-      end
-
-      def timed_out?
-        @timed_out
-      end
-
-      def cancelled?
-        @cancelled
-      end
-
-      private
-
-      def build_child_config(config)
-        config.dup
-      end
-
-      def cancel_active_children!
-        @pending.clear
-        @active.each_value do |entry|
-          entry[:token]&.cancel!
-        end
-      end
-    end
-  end
-end