phronomy 0.26.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::TaskResult}; only the execution mechanism
-    # differs.
-    #
-    # :cooperative Tool calls execute inline and must return quickly. call_async
-    # wraps their result in an already-settled TaskResult and never consumes an
-    # OffloadPool worker.
-    #
-    # :offloaded Tool calls route synchronous work through OffloadPool, whose
-    # caller-facing completion handle is also a TaskResult. 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::TaskResult.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/parallel_tool_chat.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module MultiAgent
-    # RubyLLM::Chat subclass supporting concurrent direct Tool execution.
-    #
-    # AgentInvocation installs +on_tool_call_batch+ and intercepts the whole batch
-    # before this class dispatches anything. The direct-chat fallback dispatches
-    # the complete batch concurrently; process protection remains the responsibility
-    # of Runtime's bounded executors and queues.
-    # @api private
-    class ParallelToolChat < RubyLLM::Chat
-      def initialize(cancellation_token: nil, **opts)
-        super(**opts)
-        @cancellation_token = cancellation_token
-      end
-
-      attr_writer :cancellation_token
-
-      # Registers an Agent-owned batch interceptor. The callback must return
-      # quickly or raise ToolCallIntercepted; it must not execute Tool bodies.
-      def on_tool_call_batch(&block)
-        @on[:tool_call_batch] = block
-        self
-      end
-
-      private
-
-      def handle_tool_calls(response, &block)
-        tool_calls = response.tool_calls.values
-        return super if tool_calls.size <= 1
-
-        if @on[:tool_call_batch]
-          tool_calls.each { run_callbacks(:before_message, :new_message) }
-          @on[:tool_call_batch].call(tool_calls)
-          return
-        end
-
-        # Direct ParallelToolChat fallback. Agent execution never reaches this
-        # branch because AgentInvocation installs the batch interceptor first.
-        # RubyLLM >= 1.15 additive callbacks are dispatched together with their
-        # legacy equivalents, matching RubyLLM::Chat semantics.
-        tool_calls.each do |tool_call|
-          run_callbacks(:before_message, :new_message)
-          run_callbacks(:before_tool_call, :tool_call, tool_call)
-        end
-
-        cancellation_token = @cancellation_token
-        if cancellation_token&.cancelled?
-          raise Phronomy::CancellationError,
-            "invocation cancelled before tool execution"
-        end
-
-        dispatched = tool_calls.map do |tool_call|
-          tool = tools[tool_call.name.to_sym]
-          unless tool
-            next {
-              tool_call: tool_call,
-              awaitable: nil,
-              result: {
-                error: "Model tried to call unavailable tool `#{tool_call.name}`. " \
-                  "Available tools: #{tools.keys.to_json}."
-              }
-            }
-          end
-
-          awaitable = Phronomy::Agent::ToolExecutor.call_async(
-            tool: tool,
-            args: tool_call.arguments,
-            cancellation_token: cancellation_token
-          )
-          {tool_call: tool_call, awaitable: awaitable, result: nil}
-        end
-
-        tool_results = dispatched.map do |item|
-          result = item[:awaitable] ? item[:awaitable].wait_result : item[:result]
-          {tool_call: item[:tool_call], result: result}
-        end
-
-        halt_result = nil
-        tool_results.each do |item|
-          result = item[:result]
-          run_callbacks(:after_tool_result, :tool_result, result)
-          tool_payload = result.is_a?(RubyLLM::Tool::Halt) ? result.content : result
-          content = content_like?(tool_payload) ? tool_payload : tool_payload.to_s
-          message = add_message(
-            role: :tool,
-            content: content,
-            tool_call_id: item[:tool_call].id
-          )
-          run_callbacks(:after_message, :end_message, message)
-          halt_result = result if result.is_a?(RubyLLM::Tool::Halt)
-        end
-
-        reset_tool_choice if forced_tool_choice?
-        halt_result || complete(&block)
-      end
-
-      def execute_tool(tool_call)
-        tool = tools[tool_call.name.to_sym]
-        unless tool
-          return {
-            error: "Model tried to call unavailable tool `#{tool_call.name}`. " \
-              "Available tools: #{tools.keys.to_json}."
-          }
-        end
-
-        Phronomy::Agent::ToolExecutor.call_async(
-          tool: tool,
-          args: tool_call.arguments,
-          cancellation_token: @cancellation_token
-        ).wait_result
-      end
-    end
-  end
-end