phronomy 0.15.0 → 0.16.0

data/lib/phronomy/agent/context_plan_validator.rb

@@ -0,0 +1,167 @@
+# 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)
+        validate_legacy_tool_dependencies!(all_candidates, selected_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
+
+      # Compatibility for Journal state written by the preceding stateful
+      # refactor, where assistant content, Tool Calls and Tool Results were
+      # flattened into separate Context candidates.
+      def validate_legacy_tool_dependencies!(all_candidates, selected_candidates, selected_ids)
+        all_calls = Array(all_candidates).select { |candidate| candidate.category == :tool_call }
+          .to_h { |candidate| [candidate.tool_call_id, candidate] }
+        all_results = Array(all_candidates).select { |candidate| candidate.category == :tool_result }
+          .group_by(&:tool_call_id)
+
+        selected_candidates.each do |candidate|
+          case candidate.category
+          when :tool_result
+            call = all_calls[candidate.tool_call_id]
+            unless call && selected_ids[call.candidate_id]
+              raise ArgumentError,
+                "ContextPlan selected orphan Tool Result: #{candidate.tool_call_id}"
+            end
+          when :tool_call
+            results = all_results.fetch(candidate.tool_call_id, [])
+            if results.empty?
+              raise ArgumentError,
+                "ContextPlan selected Tool Call without a Tool Result: #{candidate.tool_call_id}"
+            end
+            missing = results.reject { |result| selected_ids[result.candidate_id] }
+            unless missing.empty?
+              raise ArgumentError,
+                "ContextPlan split Tool Call/Result dependency: #{candidate.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

data/lib/phronomy/agent/context_selection_unit.rb

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

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