phronomy 0.22.0 → 0.24.0

data/lib/phronomy/agent/context_policy.rb

@@ -1,14 +1,120 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Phronomy
   module Agent
     class ContextPolicy
-      def call(_request)
+      def call(_input)
         raise NotImplementedError, "#{self.class}#call is not implemented"
       end
 
-      def descriptor
-        raise NotImplementedError, "#{self.class}#descriptor is not implemented"
+      protected
+
+      def instruction_item(
+        content:,
+        role: :system,
+        kind: :instruction,
+        content_format: nil,
+        required: false,
+        metadata: {}
+      )
+        ContextPolicyInput::InstructionItem.new(
+          id: generated_item_id(:instruction),
+          kind: kind,
+          role: role,
+          content: content,
+          content_format: content_format || inferred_content_format(content),
+          estimated_tokens: estimate_content(content),
+          required: required,
+          provenance: generated_provenance,
+          metadata: metadata
+        )
+      end
+
+      def knowledge_item(
+        content:,
+        role: :user,
+        kind: :knowledge,
+        content_format: nil,
+        required: false,
+        metadata: {}
+      )
+        ContextPolicyInput::KnowledgeItem.new(
+          id: generated_item_id(:knowledge),
+          kind: kind,
+          role: role,
+          content: content,
+          content_format: content_format || inferred_content_format(content),
+          estimated_tokens: estimate_content(content),
+          required: required,
+          provenance: generated_provenance,
+          metadata: metadata
+        )
+      end
+
+      def conversation_item(
+        content:,
+        role:,
+        kind: :conversation,
+        content_format: nil,
+        sequence: nil,
+        required: false,
+        tool_call_id: nil,
+        tool_call_ids: [],
+        delivery: :chat_message,
+        metadata: {}
+      )
+        ContextPolicyInput::ConversationItem.new(
+          id: generated_item_id(:conversation),
+          kind: kind,
+          role: role,
+          content: content,
+          content_format: content_format || inferred_content_format(content),
+          sequence: sequence,
+          estimated_tokens: estimate_content(content),
+          required: required,
+          provenance: generated_provenance,
+          tool_call_id: tool_call_id,
+          tool_call_ids: tool_call_ids,
+          delivery: delivery,
+          metadata: metadata
+        )
+      end
+
+      def plan(
+        instruction: [],
+        knowledge: [],
+        tools: [],
+        conversation: [],
+        metadata: {}
+      )
+        ContextPlan.new(
+          instruction: instruction,
+          knowledge: knowledge,
+          tools: tools,
+          conversation: conversation,
+          metadata: metadata
+        )
+      end
+
+      private
+
+      def generated_item_id(category)
+        "policy:#{category}:#{SecureRandom.uuid}".freeze
+      end
+
+      def generated_provenance
+        ContextPolicyInput::Provenance.new(origin: :policy_generated)
+      end
+
+      def inferred_content_format(content)
+        content.is_a?(String) ? :text : :json
+      end
+
+      def estimate_content(content)
+        bytes = content.is_a?(String) ? content : Phronomy::CanonicalJSON.dump(content)
+        Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
       end
     end
   end

data/lib/phronomy/agent/context_policy_input.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    ContextPolicyInput = Data.define(
+      :agent_id,
+      :execution_id,
+      :call_sequence,
+      :call_mode,
+      :instruction,
+      :knowledge,
+      :tools,
+      :conversation,
+      :token_budget,
+      :model_config,
+      :previous_manifest,
+      :metadata
+    ) do
+      def initialize(**values)
+        normalized_instruction = Array(values[:instruction]).freeze
+        normalized_knowledge = Array(values[:knowledge]).freeze
+        normalized_tools = Array(values[:tools]).freeze
+        normalized_conversation = Array(values[:conversation]).map do |group|
+          normalized_group = Array(group).freeze
+          raise ArgumentError, "ContextPolicyInput conversation groups must not be empty" if normalized_group.empty?
+          normalized_group
+        end.freeze
+
+        validate_items!(normalized_instruction, ContextPolicyInput::InstructionItem, :instruction)
+        validate_items!(normalized_knowledge, ContextPolicyInput::KnowledgeItem, :knowledge)
+        validate_items!(normalized_tools, ContextPolicyInput::ToolItem, :tools)
+        normalized_conversation.each do |group|
+          validate_items!(group, ContextPolicyInput::ConversationItem, :conversation)
+        end
+
+        call_sequence = Integer(values.fetch(:call_sequence))
+        raise ArgumentError, "ContextPolicyInput call_sequence must be positive" unless call_sequence.positive?
+
+        call_mode = values.fetch(:call_mode).to_sym
+        unless LLMInputManifest::CALL_MODES.include?(call_mode)
+          raise ArgumentError, "unknown ContextPolicyInput call_mode: #{call_mode.inspect}"
+        end
+
+        super(**values.merge(
+          agent_id: values.fetch(:agent_id).to_s.freeze,
+          execution_id: values[:execution_id]&.to_s&.freeze,
+          call_sequence: call_sequence,
+          call_mode: call_mode,
+          instruction: normalized_instruction,
+          knowledge: normalized_knowledge,
+          tools: normalized_tools,
+          conversation: normalized_conversation,
+          model_config: Immutable.copy(values[:model_config] || {}),
+          metadata: Immutable.copy(values[:metadata] || {})
+        ))
+        freeze
+      end
+
+      private
+
+      def validate_items!(items, expected_class, label)
+        invalid = items.reject { |item| item.is_a?(expected_class) }
+        return if invalid.empty?
+
+        raise ArgumentError,
+          "ContextPolicyInput #{label} contains #{invalid.first.class}; expected #{expected_class}"
+      end
+    end
+
+    class ContextPolicyInput
+      CONTENT_FORMATS = %i[text json].freeze
+      DELIVERIES = %i[ask_argument chat_message].freeze
+      FRAMEWORK_METADATA_KEYS = %w[
+        phronomy_origin
+        context_policy_origin
+        context_policy_item_id
+        context_policy_semantic_category
+        context_policy_content_format
+        context_policy_conversation_group_id
+        handoff_policy_category
+        handoff_provenance
+        selection_candidate_id
+        selection_unit_id
+        selection_unit_kind
+        journal_record_id
+        source_agent_id
+        source_execution_id
+        llm_call_id
+      ].freeze
+
+      Provenance = Data.define(
+        :origin,
+        :content_ref,
+        :record_id,
+        :agent_id,
+        :execution_id,
+        :llm_call_id
+      ) do
+        def initialize(
+          origin:,
+          content_ref: nil,
+          record_id: nil,
+          agent_id: nil,
+          execution_id: nil,
+          llm_call_id: nil
+        )
+          super(
+            origin: origin.to_sym,
+            content_ref: content_ref&.to_s&.freeze,
+            record_id: record_id&.to_s&.freeze,
+            agent_id: agent_id&.to_s&.freeze,
+            execution_id: execution_id&.to_s&.freeze,
+            llm_call_id: llm_call_id&.to_s&.freeze
+          )
+          freeze
+        end
+      end
+
+      InstructionItem = Data.define(
+        :id, :kind, :role, :content, :content_format,
+        :estimated_tokens, :required, :provenance, :metadata
+      ) do
+        def initialize(**values)
+          super(**ContextPolicyInput.send(:normalize_content_item_values, values))
+          freeze
+        end
+
+        def required? = required
+      end
+
+      KnowledgeItem = Data.define(
+        :id, :kind, :role, :content, :content_format,
+        :estimated_tokens, :required, :provenance, :metadata
+      ) do
+        def initialize(**values)
+          super(**ContextPolicyInput.send(:normalize_content_item_values, values))
+          freeze
+        end
+
+        def required? = required
+      end
+
+      ToolItem = Data.define(
+        :id, :definition, :estimated_tokens, :required, :provenance, :metadata
+      ) do
+        def initialize(**values)
+          provenance = ContextPolicyInput.send(:normalize_provenance, values[:provenance])
+          definition = Immutable.copy(values.fetch(:definition))
+          unless definition.is_a?(Hash) && definition["name"].to_s != ""
+            raise ArgumentError, "ContextPolicyInput ToolItem definition requires a non-empty name"
+          end
+
+          super(
+            id: values.fetch(:id).to_s.freeze,
+            definition: definition,
+            estimated_tokens: ContextPolicyInput.send(:normalize_estimated_tokens, values[:estimated_tokens]),
+            required: !!values[:required],
+            provenance: provenance,
+            metadata: Immutable.copy(values[:metadata] || {})
+          )
+          raise ArgumentError, "ContextPolicyInput ToolItem id must not be empty" if id.empty?
+          freeze
+        end
+
+        def required? = required
+      end
+
+      ConversationItem = Data.define(
+        :id, :kind, :role, :content, :content_format,
+        :sequence, :estimated_tokens, :required, :provenance,
+        :tool_call_id, :tool_call_ids, :delivery, :metadata
+      ) do
+        def initialize(**values)
+          normalized = ContextPolicyInput.send(:normalize_content_item_values, values)
+          delivery = (values[:delivery] || :chat_message).to_sym
+          unless ContextPolicyInput::DELIVERIES.include?(delivery)
+            raise ArgumentError, "unknown ContextPolicyInput delivery: #{delivery.inspect}"
+          end
+
+          super(**normalized.merge(
+            sequence: values[:sequence] && Integer(values[:sequence]),
+            tool_call_id: values[:tool_call_id]&.to_s&.freeze,
+            tool_call_ids: Array(values[:tool_call_ids]).compact.map(&:to_s).freeze,
+            delivery: delivery
+          ))
+          freeze
+        end
+
+        def required? = required
+
+        def with_required(required)
+          return self if required? == !!required
+          self.class.new(**to_h.merge(required: !!required))
+        end
+      end
+
+      class << self
+        private
+
+        def normalize_content_item_values(values)
+          id = values.fetch(:id).to_s.freeze
+          raise ArgumentError, "ContextPolicyInput item id must not be empty" if id.empty?
+
+          kind = values.fetch(:kind).to_sym
+          role = values[:role]&.to_sym
+          content_format = (values[:content_format] || infer_content_format(values[:content])).to_sym
+          unless ContextPolicyInput::CONTENT_FORMATS.include?(content_format)
+            raise ArgumentError, "unknown ContextPolicyInput content format: #{content_format.inspect}"
+          end
+
+          {
+            id: id,
+            kind: kind,
+            role: role,
+            content: Immutable.copy(values[:content]),
+            content_format: content_format,
+            estimated_tokens: normalize_estimated_tokens(values[:estimated_tokens]),
+            required: !!values[:required],
+            provenance: normalize_provenance(values[:provenance]),
+            metadata: Immutable.copy(values[:metadata] || {})
+          }
+        end
+
+        def infer_content_format(content)
+          content.is_a?(String) ? :text : :json
+        end
+
+        def normalize_estimated_tokens(value)
+          result = Integer(value || 0)
+          raise ArgumentError, "estimated_tokens must be non-negative" if result.negative?
+          result
+        end
+
+        def normalize_provenance(value)
+          return value if value.is_a?(ContextPolicyInput::Provenance)
+          return ContextPolicyInput::Provenance.new(origin: :unknown) if value.nil?
+          return ContextPolicyInput::Provenance.new(**value) if value.is_a?(Hash)
+
+          raise ArgumentError, "ContextPolicyInput item provenance must be Provenance or Hash"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_policy_input_builder.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class ContextPolicyInputBuilder
+      KNOWLEDGE_KINDS = %i[knowledge memory summary structured_state].freeze
+      CONVERSATION_KINDS = %i[external_message assistant_message tool_message current_input current_request].freeze
+
+      def initialize(content_loader:)
+        @content_loader = content_loader
+      end
+
+      def build(
+        agent_id:,
+        execution_id:,
+        call_sequence:,
+        call_mode:,
+        candidates:,
+        instruction:,
+        tools:,
+        token_budget:, model_config:, previous_manifest:, current_input: nil,
+        metadata: {}
+      )
+        instruction_items = Array(instruction).dup
+        knowledge = []
+        conversation = []
+
+        Array(candidates).each do |candidate|
+          case semantic_category(candidate)
+          when :instruction
+            instruction_items << instruction_item(candidate)
+          when :knowledge
+            knowledge << knowledge_item(candidate)
+          when :conversation
+            conversation << conversation_item(candidate)
+          end
+        end
+        conversation << current_input if current_input
+
+        groups = conversation_groups(
+          conversation,
+          execution_id: execution_id,
+          call_mode: call_mode
+        )
+
+        ContextPolicyInput.new(
+          agent_id: agent_id,
+          execution_id: execution_id,
+          call_sequence: call_sequence,
+          call_mode: call_mode,
+          instruction: instruction_items,
+          knowledge: knowledge,
+          tools: tools,
+          conversation: groups,
+          token_budget: token_budget,
+          model_config: model_config,
+          previous_manifest: previous_manifest,
+          metadata: metadata
+        )
+      end
+
+      private
+
+      def semantic_category(candidate)
+        explicit = candidate.metadata["context_policy_semantic_category"] ||
+          candidate.metadata[:context_policy_semantic_category]
+        if explicit
+          normalized = explicit.to_sym
+          return normalized if %i[instruction knowledge conversation].include?(normalized)
+
+          raise ArgumentError,
+            "unsupported Context Policy semantic category metadata: #{explicit.inspect}"
+        end
+
+        kind = candidate.category
+        normalized = kind.to_sym
+        return :instruction if normalized == :instruction || normalized == :handoff_responsibility
+        return :knowledge if KNOWLEDGE_KINDS.include?(normalized)
+        return :conversation if CONVERSATION_KINDS.include?(normalized)
+
+        raise ArgumentError, "unsupported Context Policy candidate category: #{kind.inspect}"
+      end
+
+      def instruction_item(candidate)
+        ContextPolicyInput::InstructionItem.new(
+          **common_content_values(candidate),
+          role: candidate.role || :system
+        )
+      end
+
+      def knowledge_item(candidate)
+        ContextPolicyInput::KnowledgeItem.new(
+          **common_content_values(candidate),
+          role: candidate.role || :user
+        )
+      end
+
+      def conversation_item(candidate)
+        values = common_content_values(candidate)
+        ContextPolicyInput::ConversationItem.new(
+          **values,
+          role: candidate.role,
+          sequence: candidate.sequence,
+          tool_call_id: candidate.tool_call_id,
+          tool_call_ids: canonical_tool_call_ids(candidate),
+          delivery: :chat_message
+        )
+      end
+
+      def common_content_values(candidate)
+        format = content_format(candidate)
+        {
+          id: candidate.candidate_id,
+          kind: candidate.category,
+          content: load_content(candidate.content_ref, format),
+          content_format: format,
+          estimated_tokens: Integer(candidate.metadata["estimated_tokens"] || 0),
+          required: candidate.constraint.required?,
+          provenance: ContextPolicyInput::Provenance.new(
+            origin: candidate.source_kind,
+            content_ref: candidate.content_ref,
+            record_id: candidate.record_id,
+            agent_id: candidate.agent_id,
+            execution_id: candidate.execution_id,
+            llm_call_id: candidate.llm_call_id
+          ),
+          metadata: candidate.metadata
+        }
+      end
+
+      def content_format(candidate)
+        explicit = candidate.metadata["content_format"] || candidate.metadata[:content_format]
+        return explicit.to_sym if explicit
+        return :json if %i[assistant_message tool_message].include?(candidate.category.to_sym)
+
+        :text
+      end
+
+      def load_content(content_ref, format)
+        bytes = @content_loader.call(content_ref)
+        return bytes if format == :text
+
+        Phronomy::CanonicalJSON.load(bytes)
+      end
+
+      def conversation_groups(items, execution_id:, call_mode:)
+        ordered = Array(items).sort_by { |item| [item.sequence || 0, item.id] }
+        assistants = ordered.select { |item| item.kind == :assistant_message }
+        tool_messages = ordered.select { |item| item.kind == :tool_message }
+        tool_messages_by_id = tool_messages.group_by(&:tool_call_id)
+        tool_messages_by_id.each do |tool_call_id, messages|
+          if tool_call_id.nil? || tool_call_id.empty?
+            raise ArgumentError, "Tool message Context item requires tool_call_id"
+          end
+          if messages.length > 1
+            raise ArgumentError, "duplicate Tool message in Context Policy input: #{tool_call_id}"
+          end
+        end
+
+        assistant_by_tool_call = {}
+        assistants.each do |assistant|
+          assistant.tool_call_ids.each do |tool_call_id|
+            if assistant_by_tool_call.key?(tool_call_id)
+              raise ArgumentError,
+                "duplicate assistant Tool Call id in Context Policy input: #{tool_call_id}"
+            end
+            assistant_by_tool_call[tool_call_id] = assistant
+          end
+        end
+
+        claimed = {}
+        groups = []
+        ordered.each do |item|
+          next if claimed[item.id]
+
+          if item.kind == :assistant_message && !item.tool_call_ids.empty?
+            messages = item.tool_call_ids.map do |tool_call_id|
+              tool_messages_by_id.fetch(tool_call_id) do
+                raise ArgumentError,
+                  "assistant Tool Call has no Tool message in Context Policy input: #{tool_call_id}"
+              end.first
+            end
+            group = ([item] + messages).uniq.sort_by { |member| [member.sequence || 0, member.id] }
+          elsif item.kind == :tool_message
+            assistant = assistant_by_tool_call[item.tool_call_id]
+            unless assistant
+              raise ArgumentError,
+                "orphan Tool message in Context Policy input: #{item.tool_call_id}"
+            end
+            next if claimed[assistant.id]
+            group = ([assistant] + assistant.tool_call_ids.map do |tool_call_id|
+              tool_messages_by_id.fetch(tool_call_id).first
+            end).uniq.sort_by { |member| [member.sequence || 0, member.id] }
+          else
+            group = [item]
+          end
+
+          group.each { |member| claimed[member.id] = true }
+          groups << group
+        end
+
+        mark_framework_required(groups, execution_id: execution_id, call_mode: call_mode)
+      end
+
+      def mark_framework_required(groups, execution_id:, call_mode:)
+        return groups.map(&:freeze).freeze unless call_mode.to_sym == :complete
+
+        current_request_ids = groups.flatten.select do |item|
+          item.kind == :external_message &&
+            item.provenance.origin == :working &&
+            item.provenance.execution_id.to_s == execution_id.to_s
+        end.map(&:id).to_h { |id| [id, true] }
+
+        current_tool_groups = groups.select do |group|
+          group.any? do |item|
+            %i[assistant_message tool_message].include?(item.kind) &&
+              item.provenance.origin == :working &&
+              item.provenance.execution_id.to_s == execution_id.to_s
+          end && group.any? { |item| item.kind == :tool_message }
+        end
+        latest_tool_group = current_tool_groups.max_by do |group|
+          group.filter_map(&:sequence).max || 0
+        end
+        latest_tool_ids = Array(latest_tool_group).map(&:id).to_h { |id| [id, true] }
+
+        groups.map do |group|
+          group.map do |item|
+            required = item.required? || current_request_ids[item.id] || latest_tool_ids[item.id]
+            item.with_required(required)
+          end.freeze
+        end.freeze
+      end
+
+      def canonical_tool_call_ids(candidate)
+        Array(candidate.metadata["tool_call_ids"] || candidate.metadata[:tool_call_ids])
+          .compact
+          .map(&:to_s)
+      end
+    end
+  end
+end