phronomy 0.22.0 → 0.23.0

data/lib/phronomy/agent/context_parts/requirements/required_context_resolver.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module ContextParts
-      module Requirements
-        class RequiredContextResolver
-          def resolve(request:, units:)
-            candidates = request.candidates.to_h { |candidate| [candidate.candidate_id, candidate] }
-            declared = request.required_coverage.to_h { |value| [value.to_s, true] }
-            latest_tool_unit = latest_current_tool_unit(request, units, candidates)
-
-            Array(units).map do |unit|
-              requirement = unit.requirement
-              if unit.unit_id == latest_tool_unit&.unit_id
-                requirement = :protocol_required
-              elsif requirement == :optional && unit.candidate_ids.any? do |candidate_id|
-                candidate = candidates.fetch(candidate_id)
-                declared[candidate.candidate_id] || declared[candidate.record_id.to_s]
-              end
-                requirement = :declared_required
-              end
-
-              next unit if requirement == unit.requirement
-
-              ContextSelectionUnit.new(
-                unit_id: unit.unit_id,
-                candidate_ids: unit.candidate_ids,
-                dependency_unit_ids: unit.dependency_unit_ids,
-                kind: unit.kind,
-                requirement: requirement,
-                priority: unit.priority,
-                sequence_range: unit.sequence_range,
-                metadata: unit.metadata
-              )
-            end.freeze
-          end
-
-          private
-
-          def latest_current_tool_unit(request, units, candidates)
-            return unless request.call_mode == :complete
-
-            Array(units).select do |unit|
-              unit.kind == :tool_exchange && unit.candidate_ids.any? do |candidate_id|
-                candidate = candidates.fetch(candidate_id)
-                candidate.source_kind == :working &&
-                  candidate.execution_id.to_s == request.execution_id.to_s
-              end
-            end.max_by { |unit| unit.sequence_range.last }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_parts/selectors/recent_first_selector.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module ContextParts
-      module Selectors
-        class RecentFirstSelector
-          def order(request:, units:)
-            candidates = request.candidates.to_h { |candidate| [candidate.candidate_id, candidate] }
-            Array(units).sort_by do |unit|
-              required_rank = (unit.requirement == :optional) ? 1 : 0
-              current_rank = current_execution_unit?(request, unit, candidates) ? 0 : 1
-              [required_rank, current_rank, -unit.priority, -unit.sequence_range.last]
-            end.freeze
-          end
-
-          private
-
-          def current_execution_unit?(request, unit, candidates)
-            unit.candidate_ids.any? do |candidate_id|
-              candidate = candidates.fetch(candidate_id)
-              candidate.execution_id.to_s == request.execution_id.to_s &&
-                candidate.source_kind == :working
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_parts/unit_builders/dependency_aware_unit_builder.rb

@@ -1,118 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-
-module Phronomy
-  module Agent
-    module ContextParts
-      module UnitBuilders
-        class DependencyAwareUnitBuilder
-          def build(candidates)
-            ordered = Array(candidates).sort_by do |candidate|
-              [candidate.sequence || 0, candidate.candidate_id]
-            end
-
-            canonical_assistants = ordered.select do |candidate|
-              candidate.category == :assistant_message
-            end
-            canonical_tool_messages = ordered.select do |candidate|
-              candidate.category == :tool_message
-            end.group_by(&:tool_call_id)
-            assistant_by_tool_call_id = canonical_assistants.each_with_object({}) do |candidate, result|
-              canonical_tool_call_ids(candidate).each do |tool_call_id|
-                if result.key?(tool_call_id)
-                  raise ArgumentError,
-                    "duplicate assistant Tool Call id in Context candidates: #{tool_call_id}"
-                end
-                result[tool_call_id] = candidate
-              end
-            end
-
-            claimed = Set.new
-            units = []
-            ordered.each do |candidate|
-              next if claimed.include?(candidate.candidate_id)
-
-              group = canonical_tool_exchange(
-                candidate,
-                assistant_by_tool_call_id: assistant_by_tool_call_id,
-                tool_messages: canonical_tool_messages
-              )
-
-              if group && !group.empty?
-                group.each { |item| claimed << item.candidate_id }
-                units << build_unit(group, kind: :tool_exchange)
-              else
-                claimed << candidate.candidate_id
-                units << build_unit([candidate], kind: :message)
-              end
-            end
-
-            units.sort_by { |unit| unit.sequence_range.first }.freeze
-          end
-
-          private
-
-          def canonical_tool_exchange(candidate, assistant_by_tool_call_id:, tool_messages:)
-            assistant = if candidate.category == :assistant_message
-              candidate
-            elsif candidate.category == :tool_message
-              assistant_by_tool_call_id[candidate.tool_call_id]
-            end
-            return unless assistant
-
-            call_ids = canonical_tool_call_ids(assistant)
-            return if call_ids.empty?
-
-            messages = call_ids.flat_map do |tool_call_id|
-              tool_messages.fetch(tool_call_id, [])
-            end
-            ([assistant] + messages).uniq.sort_by do |item|
-              [item.sequence || 0, item.candidate_id]
-            end
-          end
-
-          def canonical_tool_call_ids(candidate)
-            Array(candidate.metadata["tool_call_ids"] || candidate.metadata[:tool_call_ids])
-              .compact
-              .map(&:to_s)
-          end
-
-          def build_unit(candidates, kind:)
-            ids = candidates.map(&:candidate_id)
-            sequences = candidates.map(&:sequence).compact
-            requirements = candidates.map(&:requirement)
-            requirement = if requirements.include?(:protocol_required)
-              :protocol_required
-            elsif requirements.include?(:declared_required)
-              :declared_required
-            else
-              :optional
-            end
-            tool_call_ids = candidates.flat_map do |candidate|
-              call_ids = canonical_tool_call_ids(candidate)
-              call_ids << candidate.tool_call_id if candidate.tool_call_id
-              call_ids
-            end.compact.uniq
-            llm_call_ids = candidates.map(&:llm_call_id).compact.uniq
-            digest = Digest::SHA256.hexdigest(ids.join("\0"))[0, 20]
-
-            ContextSelectionUnit.new(
-              unit_id: "#{kind}:#{digest}",
-              candidate_ids: ids,
-              dependency_unit_ids: [],
-              kind: kind,
-              requirement: requirement,
-              priority: candidates.map(&:priority).max || 0,
-              sequence_range: [sequences.min || 0, sequences.max || 0],
-              metadata: {
-                "tool_call_ids" => tool_call_ids,
-                "llm_call_ids" => llm_call_ids
-              }
-            )
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_policy_descriptor.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-
-module Phronomy
-  module Agent
-    ContextPolicyDescriptor = Data.define(:id, :version, :config) do
-      def initialize(id:, version:, config: {})
-        normalized_config = Immutable.copy(config || {})
-        Immutable.validate_canonical_json!(normalized_config, label: "Context Policy config")
-        super(
-          id: id.to_s.freeze,
-          version: Integer(version),
-          config: normalized_config
-        )
-        raise ArgumentError, "Context Policy id must not be empty" if id.empty?
-        raise ArgumentError, "Context Policy version must be positive" unless version.positive?
-        freeze
-      end
-
-      def self.from_h(hash)
-        descriptor = new(
-          id: hash.fetch("id") { hash.fetch(:id) },
-          version: hash.fetch("version") { hash.fetch(:version) },
-          config: hash["config"] || hash[:config] || {}
-        )
-        expected_digest = hash["config_digest"] || hash[:config_digest]
-        if expected_digest && expected_digest.to_s != descriptor.config_digest
-          raise Phronomy::ConfigurationError,
-            "Context Policy config digest mismatch for #{descriptor.id}@#{descriptor.version}"
-        end
-        descriptor
-      end
-
-      def config_digest
-        "sha256:#{Digest::SHA256.hexdigest(Phronomy::CanonicalJSON.dump(config))}"
-      end
-
-      def to_h
-        {
-          "id" => id,
-          "version" => version,
-          "config" => config,
-          "config_digest" => config_digest
-        }
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_policy_registry.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    class ContextPolicyRegistry
-      class << self
-        def default
-          @default ||= new.tap do |registry|
-            registry.register(id: "default-recent-v1", version: 1) do |config|
-              ContextPolicies::Default.new(config)
-            end
-          end
-        end
-      end
-
-      def initialize
-        @factories = {}
-        @mutex = Mutex.new
-      end
-
-      def register(id:, version:, &factory)
-        raise ArgumentError, "Context Policy factory is required" unless factory
-
-        key = [id.to_s, Integer(version)].freeze
-        @mutex.synchronize do
-          raise ArgumentError, "Context Policy already registered: #{key.join("@")}" if @factories.key?(key)
-          @factories[key] = factory
-        end
-        self
-      end
-
-      def resolve(descriptor)
-        key = [descriptor.id.to_s, Integer(descriptor.version)]
-        factory = @mutex.synchronize { @factories[key] }
-        raise Phronomy::ConfigurationError, "Unknown Context Policy: #{key.join("@")}" unless factory
-
-        policy = factory.call(descriptor.config)
-        unless policy.is_a?(ContextPolicy)
-          raise Phronomy::ConfigurationError,
-            "Context Policy factory returned #{policy.class}, expected #{ContextPolicy}"
-        end
-        policy
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_request.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    ContextRequest = Data.define(
-      :agent_id,
-      :execution_id,
-      :call_sequence,
-      :call_mode,
-      :candidates,
-      :token_budget,
-      :model_config,
-      :previous_manifest,
-      :required_coverage,
-      :parts,
-      :metadata
-    ) do
-      def initialize(**values)
-        super(**values.merge(
-          agent_id: values.fetch(:agent_id).to_s.freeze,
-          execution_id: values[:execution_id]&.to_s&.freeze,
-          call_sequence: Integer(values.fetch(:call_sequence)),
-          call_mode: values.fetch(:call_mode).to_sym,
-          candidates: Array(values[:candidates]).freeze,
-          model_config: Immutable.copy(values[:model_config] || {}),
-          required_coverage: Array(values[:required_coverage]).map(&:to_s).freeze,
-          parts: (values[:parts] || {}).dup.freeze,
-          metadata: Immutable.copy(values[:metadata] || {})
-        ))
-        raise ArgumentError, "ContextRequest call_sequence must be positive" unless call_sequence.positive?
-        freeze
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_selection_unit.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    ContextSelectionUnit = Data.define(
-      :unit_id,
-      :candidate_ids,
-      :dependency_unit_ids,
-      :kind,
-      :requirement,
-      :priority,
-      :sequence_range,
-      :metadata
-    ) do
-      def initialize(**values)
-        normalized = values.merge(
-          unit_id: values.fetch(:unit_id).to_s.freeze,
-          candidate_ids: Array(values[:candidate_ids]).map(&:to_s).freeze,
-          dependency_unit_ids: Array(values[:dependency_unit_ids]).map(&:to_s).freeze,
-          kind: values.fetch(:kind).to_sym,
-          requirement: (values[:requirement] || :optional).to_sym,
-          priority: Integer(values[:priority] || 0),
-          sequence_range: Array(values[:sequence_range]).map { |v| Integer(v) }.freeze,
-          metadata: Immutable.copy(values[:metadata] || {})
-        )
-        unless %i[protocol_required declared_required optional].include?(normalized[:requirement])
-          raise ArgumentError, "unknown ContextSelectionUnit requirement: #{normalized[:requirement].inspect}"
-        end
-        unless normalized[:sequence_range].length == 2
-          raise ArgumentError, "ContextSelectionUnit sequence_range must contain two integers"
-        end
-
-        super(**normalized)
-        freeze
-      end
-    end
-  end
-end

data/lib/phronomy/agent/derived_content_spec.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    DerivedContentSpec = Data.define(
-      :content,
-      :content_format,
-      :category,
-      :role,
-      :coverage_candidate_ids,
-      :source_record_ids,
-      :source_content_refs,
-      :transformer_id,
-      :transformer_version,
-      :metadata
-    ) do
-      def initialize(**values)
-        super(**values.merge(
-          content: Immutable.copy(values[:content]),
-          content_format: values.fetch(:content_format).to_sym,
-          category: values.fetch(:category).to_sym,
-          role: values[:role]&.to_sym,
-          coverage_candidate_ids: Array(values[:coverage_candidate_ids]).map(&:to_s).freeze,
-          source_record_ids: Array(values[:source_record_ids]).map(&:to_s).freeze,
-          source_content_refs: Array(values[:source_content_refs]).map(&:to_s).freeze,
-          transformer_id: values.fetch(:transformer_id).to_s.freeze,
-          transformer_version: Integer(values.fetch(:transformer_version)),
-          metadata: Immutable.copy(values[:metadata] || {})
-        ))
-        freeze
-      end
-    end
-  end
-end

data/lib/phronomy/agent/runner.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Orchestrates a multi-agent conversation by routing between agents
-    # based on handoff tool calls detected in each agent's conversation history.
-    #
-    # Runner configures handoff tools on source agent instances at construction
-    # time, then coordinates invocations: after each agent turn it inspects
-    # the returned messages for a handoff sentinel and routes accordingly.
-    #
-    # @example Linear handoff (triage → billing)
-    #   triage  = TriageAgent.new
-    #   billing = BillingAgent.new
-    #   runner  = Phronomy::Agent::Runner.new(
-    #     agents: [triage, billing],
-    #     routes: { triage => [billing] }
-    #   )
-    #   result = runner.invoke("I need help with my invoice")
-    #   puts result[:output]
-    #   puts result[:agent].class  # => BillingAgent
-    class Runner
-      # Maximum number of agent handoffs allowed per invoke call.
-      MAX_HANDOFFS = 20
-
-      attr_reader :agents
-
-      # @param agents [Array<Phronomy::Agent::Base>]
-      #   agents managed by this runner; first element is the entry agent
-      # @param routes [Hash{Phronomy::Agent::Base => Array<Phronomy::Agent::Base>}]
-      #   declares which target agents each source agent may hand off to;
-      #   when omitted no handoffs are configured and the entry agent handles everything
-      # @api public
-      def initialize(agents:, routes: {})
-        @agents = Array(agents)
-        raise ArgumentError, "At least one agent is required" if @agents.empty?
-
-        @entry_agent = @agents.first
-        @sentinel_map = {}
-        build_handoffs(routes)
-      end
-
-      # Invokes the runner with the given input, routing between agents as needed.
-      # Stops when an agent's turn produces no handoff signal, or when MAX_HANDOFFS
-      # is reached (raises HandoffError in that case).
-      #
-      # @param input  [String, Hash] the initial user message
-      # @param config [Hash] forwarded to each agent's #invoke
-      # @return [Hash] { output:, messages:, usage:, agent: }
-      # @raise [Phronomy::HandoffError] if more than MAX_HANDOFFS handoffs occur
-      # @api public
-      def invoke(input, config: {})
-        current = @entry_agent
-        handoffs_taken = 0
-
-        loop do
-          # Check before invoking so we raise after exactly MAX_HANDOFFS handoffs,
-          # not after MAX_HANDOFFS + 1 LLM calls.
-          if handoffs_taken >= MAX_HANDOFFS
-            raise Phronomy::HandoffError, "Exceeded maximum handoffs (#{MAX_HANDOFFS})"
-          end
-
-          result = current.invoke(input, config: config)
-          target = find_handoff_target(result[:messages])
-          return result.merge(agent: current) unless target
-
-          current = target
-          handoffs_taken += 1
-        end
-      end
-
-      private
-
-      def build_handoffs(routes)
-        routes.each do |source_agent, target_agents|
-          Array(target_agents).each do |target_agent|
-            handoff = Phronomy::MultiAgent::Handoff.new(target_agent: target_agent)
-            @sentinel_map[handoff.sentinel] = target_agent
-            source_agent._add_handoff_tool(handoff.to_tool_class)
-          end
-        end
-      end
-
-      def find_handoff_target(messages)
-        messages.reverse_each do |msg|
-          next unless msg.role.to_sym == :tool
-
-          content = msg.content.to_s
-          next unless content.start_with?(Phronomy::MultiAgent::Handoff::SENTINEL_PREFIX)
-
-          return @sentinel_map[content]
-        end
-        nil
-      end
-    end
-  end
-end