phronomy 0.27.0 → 0.29.0

data/lib/phronomy/agent/concerns/before_llm_input.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Concerns
-      module BeforeLLMInput
-        def self.included(base)
-          base.extend(ClassMethods)
-        end
-
-        module ClassMethods
-          def before_llm_input(callable = nil, &block)
-            if callable.nil? && !block_given?
-              @before_llm_input
-            else
-              @before_llm_input = callable || block
-            end
-          end
-
-          def _before_llm_input = @before_llm_input
-        end
-
-        attr_accessor :before_llm_input
-
-        private
-
-        def run_before_llm_input_hooks(call_sequence:, config:)
-          hooks = [
-            Phronomy.configuration.before_llm_input,
-            self.class._before_llm_input,
-            @before_llm_input
-          ].compact
-          return LLMInputPatch.empty if hooks.empty?
-
-          definition = self.class.agent_definition
-          context = LLMInputBuildContext.new(
-            agent_id: agent_id,
-            agent_definition_id: definition.fetch(:id),
-            agent_definition_version: definition.fetch(:version),
-            config: config,
-            call_sequence: call_sequence
-          )
-          model_patch = {}
-          segments = []
-
-          hooks.each do |hook|
-            result = hook.call(context)
-            check_cancellation!(config, "invocation cancelled during before_llm_input hook")
-            next if result.nil?
-            unless result.is_a?(LLMInputPatch)
-              raise TypeError,
-                "before_llm_input must return LLMInputPatch or nil, got #{result.class}"
-            end
-            model_patch.merge!(result.model_config_patch) if result.model_config_patch
-            segments.concat(Array(result.segment_candidates))
-          end
-
-          LLMInputPatch.new(
-            model_config_patch: model_patch.empty? ? nil : model_patch,
-            segment_candidates: segments.empty? ? nil : segments
-          )
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/concerns/error_translation.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Concerns
-      # Translates RubyLLM transport errors into the corresponding Phronomy error
-      # classes so that callers can rescue Phronomy-namespaced exceptions rather
-      # than coupling themselves to the underlying provider library.
-      #
-      # Included in {Phronomy::Agent::Base}.
-      module ErrorTranslation
-        private
-
-        # Re-raises +error+ as the most specific Phronomy error class that
-        # corresponds to it.  Non-RubyLLM errors are re-raised unchanged.
-        # The original exception is available as +#cause+ on the translated error.
-        #
-        # Must be called from within an active +rescue+ block so that Ruby
-        # automatically sets +#cause+ on the new exception.
-        #
-        # @param error [Exception]
-        # @raise [Phronomy::RateLimitError] for provider HTTP 429
-        # @raise [Phronomy::AuthenticationError] for provider HTTP 401 / 403
-        # @raise [Phronomy::ContextLengthError] for context window overflow
-        # @raise [Phronomy::TransportError] for all other +RubyLLM::Error+ subclasses
-        # @raise re-raises +error+ unchanged for non-RubyLLM exceptions
-        # @api private
-        def translate_and_reraise!(error)
-          case error
-          when RubyLLM::RateLimitError
-            raise Phronomy::RateLimitError, error.message
-          when RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError
-            raise Phronomy::AuthenticationError, error.message
-          when RubyLLM::ContextLengthExceededError
-            raise Phronomy::ContextLengthError, error.message
-          when RubyLLM::Error
-            raise Phronomy::TransportError, error.message
-          else
-            raise error # preserve original class, message, and backtrace
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/concerns/filterable.rb

@@ -1,184 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Concerns
-      # Adds input, output, and tool-result filter support to an agent.
-      #
-      # Filters transform (or block) values at three call sites:
-      #   - *input*       — the raw user input string, before the LLM is called
-      #   - *output*      — the final LLM output string, before it is returned
-      #   - *tool result* — the return value of each tool call
-      #
-      # Each filter in the chain receives the value returned by the previous one.
-      # A {Phronomy::FilterBlockError} raised inside any filter propagates to the
-      # caller.
-      #
-      # @api private
-      module Filterable
-        def self.included(base)
-          base.extend(ClassMethods)
-        end
-
-        # Class-level DSL mixed into the including agent class.
-        module ClassMethods
-          # Registers a filter applied to every invocation's user input.
-          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
-          # when a class is given it is instantiated with +.new+.
-          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
-          # @return [void]
-          # @api public
-          def input_filter(filter)
-            @_class_input_filters ||= []
-            @_class_input_filters << _resolve_filter(filter)
-          end
-
-          # Registers a filter applied to every invocation's final LLM output.
-          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
-          # when a class is given it is instantiated with +.new+.
-          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
-          # @return [void]
-          # @api public
-          def output_filter(filter)
-            @_class_output_filters ||= []
-            @_class_output_filters << _resolve_filter(filter)
-          end
-
-          # Registers a filter applied to every tool result for all tools.
-          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
-          # when a class is given it is instantiated with +.new+.
-          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
-          # @return [void]
-          # @api public
-          def tool_result_filter(filter)
-            @_class_tool_result_filters ||= []
-            @_class_tool_result_filters << _resolve_filter(filter)
-          end
-
-          # @return [Array<Phronomy::Filter::Base>]
-          # @api private
-          def _class_input_filters
-            @_class_input_filters || []
-          end
-
-          # @return [Array<Phronomy::Filter::Base>]
-          # @api private
-          def _class_output_filters
-            @_class_output_filters || []
-          end
-
-          # @return [Array<Phronomy::Filter::Base>]
-          # @api private
-          def _class_tool_result_filters
-            @_class_tool_result_filters || []
-          end
-
-          private
-
-          # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
-          # otherwise return the object as-is.
-          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
-          # @return [Phronomy::Filter::Base]
-          # @api private
-          def _resolve_filter(filter)
-            filter.is_a?(Class) ? filter.new : filter
-          end
-        end
-
-        # Registers an input filter on this instance.
-        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
-        # when a class is given it is instantiated with +.new+.
-        # Runs in addition to any class-level input filters.
-        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
-        # @return [self]
-        # @api public
-        def add_input_filter(filter)
-          @_instance_input_filters ||= []
-          @_instance_input_filters << _resolve_filter(filter)
-          self
-        end
-
-        # Registers an output filter on this instance.
-        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
-        # when a class is given it is instantiated with +.new+.
-        # Runs in addition to any class-level output filters.
-        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
-        # @return [self]
-        # @api public
-        def add_output_filter(filter)
-          @_instance_output_filters ||= []
-          @_instance_output_filters << _resolve_filter(filter)
-          self
-        end
-
-        # Registers a tool result filter on this instance.
-        #
-        # When called with two arguments, the filter is scoped to the given tool
-        # class only.  When called with one argument, it applies to all tools.
-        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
-        # when a class is given it is instantiated with +.new+.
-        #
-        # @overload add_tool_result_filter(filter)
-        #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>] applied to every tool
-        # @overload add_tool_result_filter(tool_class, filter)
-        #   @param tool_class [Class] scope the filter to this tool
-        #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
-        # @return [self]
-        # @api public
-        def add_tool_result_filter(tool_class_or_filter, filter = nil)
-          if filter.nil?
-            # Single-argument form: apply to all tools.
-            @_instance_tool_result_filters ||= []
-            @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
-          else
-            # Two-argument form: scoped to one tool class.
-            @_scoped_tool_result_filters ||= {}
-            (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
-          end
-          self
-        end
-
-        private
-
-        # Run input filters (class-level then instance-level).
-        # @param input [String, Hash] the raw user input
-        # @return [String, Hash] the (possibly transformed) input
-        # @api private
-        def run_input_filters!(input)
-          class_filters = self.class._class_input_filters
-          inst_filters = @_instance_input_filters || []
-          (class_filters + inst_filters).inject(input) { |val, f| f.call(val) }
-        end
-
-        # Run output filters (class-level then instance-level).
-        # @param output [String] the LLM output
-        # @return [String] the (possibly transformed) output
-        # @api private
-        def run_output_filters!(output)
-          class_filters = self.class._class_output_filters
-          inst_filters = @_instance_output_filters || []
-          (class_filters + inst_filters).inject(output) { |val, f| f.call(val) }
-        end
-
-        # Collect all tool-result filters (global + scoped) for a given tool class.
-        # @param tool_class [Class]
-        # @return [Array<Phronomy::Filter::Base>]
-        # @api private
-        def _tool_result_filters_for(tool_class)
-          global = self.class._class_tool_result_filters + (@_instance_tool_result_filters || [])
-          scoped = (@_scoped_tool_result_filters || {})[tool_class] || []
-          global + scoped
-        end
-
-        # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
-        # otherwise return the object as-is.
-        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
-        # @return [Phronomy::Filter::Base]
-        # @api private
-        def _resolve_filter(filter)
-          filter.is_a?(Class) ? filter.new : filter
-        end
-      end
-    end
-  end
-end