phronomy 0.15.1 → 0.17.0

data/lib/phronomy/agent/context_parts/budget/token_budget_packer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module ContextParts
+      module Budget
+        class TokenBudgetPacker
+          def pack(request:, units:)
+            return Array(units).freeze unless request.token_budget
+
+            candidate_index = request.candidates.to_h { |candidate| [candidate.candidate_id, candidate] }
+            mandatory = Integer(request.metadata["mandatory_token_estimate"] || 0)
+            limit = request.token_budget.effective_input_limit
+            if mandatory > limit
+              raise Phronomy::ContextBudgetExceededError,
+                "Mandatory content (estimated #{mandatory} tokens) exceeds " \
+                "available input budget (#{limit} tokens)"
+            end
+
+            remaining = limit - mandatory
+            required, optional = Array(units).partition { |unit| unit.requirement != :optional }
+            required_cost = required.sum { |unit| unit_cost(unit, candidate_index) }
+            if required_cost > remaining
+              raise Phronomy::ContextBudgetExceededError,
+                "Required Context (estimated #{required_cost} tokens) exceeds " \
+                "remaining input budget (#{remaining} tokens after mandatory content)"
+            end
+
+            selected = required.dup
+            remaining -= required_cost
+            optional.each do |unit|
+              cost = unit_cost(unit, candidate_index)
+              next if cost > remaining
+
+              selected << unit
+              remaining -= cost
+            end
+            selected.freeze
+          end
+
+          private
+
+          def unit_cost(unit, candidate_index)
+            unit.candidate_ids.sum do |candidate_id|
+              candidate = candidate_index.fetch(candidate_id)
+              Integer(candidate.metadata["estimated_tokens"] || 0)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# 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

@@ -0,0 +1,30 @@
+# 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

@@ -0,0 +1,118 @@
+# 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_parts/validators/final_budget_validator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module ContextParts
+      module Validators
+        class FinalBudgetValidator
+          def initialize(content_loader:)
+            @content_loader = content_loader
+          end
+
+          def validate!(token_budget:, segments:, extra_values: [])
+            return 0 unless token_budget
+
+            estimated = Array(segments).sum do |segment|
+              Phronomy::LlmContextWindow::TokenEstimator.estimate(
+                @content_loader.call(segment.fetch(:content_ref))
+              )
+            end
+            estimated += Array(extra_values).sum do |value|
+              bytes = value.is_a?(String) ? value : Phronomy::CanonicalJSON.dump(value)
+              Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
+            end
+
+            limit = token_budget.effective_input_limit
+            if estimated > limit
+              raise Phronomy::ContextBudgetExceededError,
+                "Canonical LLM input (estimated #{estimated} tokens) exceeds " \
+                "available input budget (#{limit} tokens)"
+            end
+            estimated
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_plan.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    ContextPlan = Data.define(
+      :selected_unit_ids,
+      :derived_contents,
+      :selected_tool_ids,
+      :ordering_hints,
+      :policy_descriptor,
+      :metadata
+    ) do
+      def initialize(**values)
+        super(**values.merge(
+          selected_unit_ids: Array(values[:selected_unit_ids]).map(&:to_s).freeze,
+          derived_contents: Array(values[:derived_contents]).freeze,
+          selected_tool_ids: Array(values[:selected_tool_ids]).map(&:to_s).freeze,
+          ordering_hints: Immutable.copy(values[:ordering_hints] || {}),
+          metadata: Immutable.copy(values[:metadata] || {})
+        ))
+        freeze
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_plan_validator.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class ContextPlanValidator
+      ValidatedContextPlan = Data.define(
+        :plan, :units, :selected_units, :selected_candidates
+      ) do
+        def initialize(**values)
+          super(**values.merge(
+            units: Array(values[:units]).freeze,
+            selected_units: Array(values[:selected_units]).freeze,
+            selected_candidates: Array(values[:selected_candidates]).freeze
+          ))
+          freeze
+        end
+      end
+
+      def validate!(request:, plan:)
+        unless plan.is_a?(ContextPlan)
+          raise ArgumentError, "Context Policy returned #{plan.class}, expected #{ContextPlan}"
+        end
+
+        units = request.parts.fetch(:unit_builder).build(request.candidates)
+        units = request.parts.fetch(:required_context_resolver).resolve(
+          request: request,
+          units: units
+        )
+        unit_index = units.to_h { |unit| [unit.unit_id, unit] }
+        unknown = plan.selected_unit_ids.reject { |unit_id| unit_index.key?(unit_id) }
+        raise ArgumentError, "ContextPlan contains unknown units: #{unknown.inspect}" unless unknown.empty?
+
+        selected_units = plan.selected_unit_ids.map { |unit_id| unit_index.fetch(unit_id) }
+        required = units.reject { |unit| unit.requirement == :optional }.map(&:unit_id)
+        missing_required = required - plan.selected_unit_ids
+        unless missing_required.empty?
+          raise Phronomy::ContextBudgetExceededError,
+            "ContextPlan omitted required units: #{missing_required.inspect}"
+        end
+
+        candidate_index = request.candidates.to_h { |candidate| [candidate.candidate_id, candidate] }
+        selected_candidates = selected_units.flat_map(&:candidate_ids).uniq.map do |candidate_id|
+          candidate_index.fetch(candidate_id)
+        end
+        validate_tool_dependencies!(request.candidates, selected_candidates)
+        validate_derived_contents!(request, plan)
+
+        ValidatedContextPlan.new(
+          plan: plan,
+          units: units,
+          selected_units: selected_units,
+          selected_candidates: selected_candidates
+        )
+      end
+
+      private
+
+      def validate_tool_dependencies!(all_candidates, selected_candidates)
+        selected_ids = selected_candidates.to_h { |candidate| [candidate.candidate_id, true] }
+        validate_canonical_tool_dependencies!(all_candidates, selected_ids)
+      end
+
+      def validate_canonical_tool_dependencies!(all_candidates, selected_ids)
+        assistants = Array(all_candidates).select { |candidate| candidate.category == :assistant_message }
+        tool_messages = Array(all_candidates).select { |candidate| candidate.category == :tool_message }
+          .group_by(&:tool_call_id)
+        assistant_by_tool_call_id = {}
+
+        tool_messages.each do |tool_call_id, messages|
+          if messages.length > 1
+            raise ArgumentError, "duplicate Tool message in Context candidates: #{tool_call_id}"
+          end
+        end
+
+        assistants.each do |assistant|
+          canonical_tool_call_ids(assistant).each do |tool_call_id|
+            if assistant_by_tool_call_id.key?(tool_call_id)
+              raise ArgumentError,
+                "duplicate assistant Tool Call id in Context candidates: #{tool_call_id}"
+            end
+            assistant_by_tool_call_id[tool_call_id] = assistant
+          end
+        end
+
+        assistants.each do |assistant|
+          next unless selected_ids[assistant.candidate_id]
+
+          canonical_tool_call_ids(assistant).each do |tool_call_id|
+            messages = tool_messages.fetch(tool_call_id, [])
+            if messages.empty?
+              raise ArgumentError,
+                "ContextPlan selected assistant Tool Call without a Tool message: #{tool_call_id}"
+            end
+            missing = messages.reject { |message| selected_ids[message.candidate_id] }
+            unless missing.empty?
+              raise ArgumentError,
+                "ContextPlan split assistant/Tool message dependency: #{tool_call_id}"
+            end
+          end
+        end
+
+        tool_messages.each do |tool_call_id, messages|
+          messages.each do |message|
+            next unless selected_ids[message.candidate_id]
+
+            assistant = assistant_by_tool_call_id[tool_call_id]
+            unless assistant && selected_ids[assistant.candidate_id]
+              raise ArgumentError,
+                "ContextPlan selected orphan Tool message: #{tool_call_id}"
+            end
+          end
+        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 validate_derived_contents!(request, plan)
+        known = request.candidates.to_h { |candidate| [candidate.candidate_id, true] }
+        plan.derived_contents.each do |derived|
+          unless derived.is_a?(DerivedContentSpec)
+            raise ArgumentError,
+              "ContextPlan derived content must be DerivedContentSpec, got #{derived.class}"
+          end
+          unknown = derived.coverage_candidate_ids.reject { |id| known[id] }
+          raise ArgumentError, "Derived content covers unknown candidates: #{unknown.inspect}" unless unknown.empty?
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_policies/default.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module ContextPolicies
+      class Default < ContextPolicy
+        DESCRIPTOR = ContextPolicyDescriptor.new(
+          id: "default-recent-v1",
+          version: 1,
+          config: {}
+        )
+
+        def initialize(config = {})
+          @config = Immutable.copy(config || {})
+        end
+
+        def descriptor
+          return DESCRIPTOR if @config.empty?
+          ContextPolicyDescriptor.new(id: DESCRIPTOR.id, version: DESCRIPTOR.version, config: @config)
+        end
+
+        def call(request)
+          units = request.parts.fetch(:unit_builder).build(request.candidates)
+          units = request.parts.fetch(:required_context_resolver).resolve(
+            request: request,
+            units: units
+          )
+          ordered = request.parts.fetch(:recent_first_selector).order(
+            request: request,
+            units: units
+          )
+          selected = request.parts.fetch(:token_budget_packer).pack(
+            request: request,
+            units: ordered
+          )
+
+          ContextPlan.new(
+            selected_unit_ids: selected.map(&:unit_id),
+            derived_contents: [],
+            selected_tool_ids: [],
+            ordering_hints: {"history" => "chronological"},
+            policy_descriptor: descriptor,
+            metadata: {
+              "candidate_count" => request.candidates.length,
+              "unit_count" => units.length,
+              "selected_unit_count" => selected.length
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_policy.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class ContextPolicy
+      def call(_request)
+        raise NotImplementedError, "#{self.class}#call is not implemented"
+      end
+
+      def descriptor
+        raise NotImplementedError, "#{self.class}#descriptor is not implemented"
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_policy_descriptor.rb

@@ -0,0 +1,49 @@
+# 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

@@ -0,0 +1,46 @@
+# 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

@@ -0,0 +1,35 @@
+# 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