activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/concerns/observers.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  # Provides observer and interceptor functionality for monitoring and modifying
+  # the prompt generation lifecycle.
+  #
+  # Observers are notified when prompts are generated and can react to events
+  # without modifying the prompt itself. Common use cases include logging,
+  # analytics, auditing, and notifications.
+  #
+  # Interceptors are called before prompts are sent to AI providers and can
+  # modify or prevent the prompt from being sent. Common use cases include
+  # content filtering, prompt modification, access control, and rate limiting.
+  module Observers
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Register one or more Observers which will be notified when prompt is generated.
+      #
+      # @param observers [Array<Class, String, Symbol>] Observer classes or names to register
+      # @return [void]
+      #
+      # @example Register multiple observers
+      #   MyAgent.register_observers(PromptLogger, :analytics_tracker)
+      def register_observers(*observers)
+        observers.flatten.compact.each { |observer| register_observer(observer) }
+      end
+
+      # Unregister one or more previously registered Observers.
+      #
+      # @param observers [Array<Class, String, Symbol>] Observer classes or names to unregister
+      # @return [void]
+      #
+      # @example Unregister multiple observers
+      #   MyAgent.unregister_observers(PromptLogger, :analytics_tracker)
+      def unregister_observers(*observers)
+        observers.flatten.compact.each { |observer| unregister_observer(observer) }
+      end
+
+      # Register one or more Interceptors which will be called before prompt is sent.
+      #
+      # @param interceptors [Array<Class, String, Symbol>] Interceptor classes or names to register
+      # @return [void]
+      #
+      # @example Register multiple interceptors
+      #   MyAgent.register_interceptors(ContentFilter, :rate_limiter)
+      def register_interceptors(*interceptors)
+        interceptors.flatten.compact.each { |interceptor| register_interceptor(interceptor) }
+      end
+
+      # Unregister one or more previously registered Interceptors.
+      #
+      # @param interceptors [Array<Class, String, Symbol>] Interceptor classes or names to unregister
+      # @return [void]
+      #
+      # @example Unregister multiple interceptors
+      #   MyAgent.unregister_interceptors(ContentFilter, :rate_limiter)
+      def unregister_interceptors(*interceptors)
+        interceptors.flatten.compact.each { |interceptor| unregister_interceptor(interceptor) }
+      end
+
+      # Register an Observer which will be notified when prompt is generated.
+      #
+      # Either a class, string, or symbol can be passed in as the Observer.
+      # If a string or symbol is passed in it will be camelized and constantized.
+      #
+      # @param observer [Class, String, Symbol] The observer to register
+      # @return [void]
+      #
+      # @example Register with class
+      #   MyAgent.register_observer(PromptLogger)
+      #
+      # @example Register with string
+      #   MyAgent.register_observer("PromptLogger")
+      #
+      # @example Register with symbol
+      #   MyAgent.register_observer(:prompt_logger)
+      def register_observer(observer)
+        Prompt.register_observer(observer_class_for(observer))
+      end
+
+      # Unregister a previously registered Observer.
+      #
+      # Either a class, string, or symbol can be passed in as the Observer.
+      # If a string or symbol is passed in it will be camelized and constantized.
+      #
+      # @param observer [Class, String, Symbol] The observer to unregister
+      # @return [void]
+      #
+      # @example Unregister with class
+      #   MyAgent.unregister_observer(PromptLogger)
+      def unregister_observer(observer)
+        Prompt.unregister_observer(observer_class_for(observer))
+      end
+
+      # Register an Interceptor which will be called before prompt is sent.
+      #
+      # Either a class, string, or symbol can be passed in as the Interceptor.
+      # If a string or symbol is passed in it will be camelized and constantized.
+      #
+      # @param interceptor [Class, String, Symbol] The interceptor to register
+      # @return [void]
+      #
+      # @example Register with class
+      #   MyAgent.register_interceptor(ContentFilter)
+      #
+      # @example Register with string
+      #   MyAgent.register_interceptor("ContentFilter")
+      #
+      # @example Register with symbol
+      #   MyAgent.register_interceptor(:content_filter)
+      def register_interceptor(interceptor)
+        Prompt.register_interceptor(observer_class_for(interceptor))
+      end
+
+      # Unregister a previously registered Interceptor.
+      #
+      # Either a class, string, or symbol can be passed in as the Interceptor.
+      # If a string or symbol is passed in it will be camelized and constantized.
+      #
+      # @param interceptor [Class, String, Symbol] The interceptor to unregister
+      # @return [void]
+      #
+      # @example Unregister with class
+      #   MyAgent.unregister_interceptor(ContentFilter)
+      def unregister_interceptor(interceptor)
+        Prompt.unregister_interceptor(observer_class_for(interceptor))
+      end
+
+      private
+
+      # Converts observer/interceptor value to class.
+      #
+      # @param value [Class, String, Symbol] The observer/interceptor identifier
+      # @return [Class] The observer/interceptor class
+      # @api private
+      def observer_class_for(value) # :nodoc:
+        case value
+        when String, Symbol
+          value.to_s.camelize.constantize
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/concerns/parameterized.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  # Provides parameterization support for agents, allowing you to pass variables
+  # to agent actions that can be used in templates.
+  #
+  # When included in an agent class, this concern enables the ability to pass
+  # parameters when calling agent actions, making agents reusable with different
+  # data contexts.
+  #
+  # @example Basic usage
+  #   class WelcomeAgent < ActiveAgent::Base
+  #     def greet
+  #       # Template can access params[:user_name]
+  #     end
+  #   end
+  #
+  #   # Pass parameters to the agent action
+  #   WelcomeAgent.with(user_name: "Alice").greet.generate
+  #
+  # @example Using in templates
+  #   # In greet.txt.erb template:
+  #   # Hello <%= params[:user_name] %>!
+  #
+  # @example Multiple parameters
+  #   OrderAgent.with(order_id: 123, customer: "John").process_order.generate
+  #
+  module Parameterized
+    extend ActiveSupport::Concern
+
+    included do
+      attr_writer :params
+
+      # Returns the parameters hash for this agent instance.
+      #
+      # @return [Hash] the parameters hash, defaults to empty hash if not set
+      def params
+        @params ||= {}
+      end
+    end
+
+    class_methods do
+      # Creates a parameterized agent proxy that will pass the given parameters
+      # to the agent instance when an action is called.
+      #
+      # @param params [Hash] the parameters to pass to the agent instance
+      # @return [ActiveAgent::Parameterized::Agent] a proxy object
+      #   that will create parameterized generations when actions are called
+      #
+      # @example
+      #   UserAgent.with(user_id: 123).send_notification.generate
+      #
+      def with(params = {})
+        ActiveAgent::Parameterized::Agent.new(self, params)
+      end
+      alias_method :prompt_with, :with
+
+      # Creates a direct prompt generation without defining an action method.
+      #
+      # This allows you to generate prompts inline without needing to define
+      # an action method on the agent class.
+      #
+      # @param messages [Array] message strings or hashes to add to conversation
+      # @param options [Hash] parameters to merge into prompt context
+      # @return [ActiveAgent::Parameterized::Generation] a generation instance
+      #   ready for generate_now, generate_later, etc.
+      #
+      # @example Direct prompt generation
+      #   MyAgent.prompt(message: "Hello world").generate_now
+      #
+      # @example With multiple messages
+      #   MyAgent.prompt(messages: ["First", "Second"]).generate_now
+      #
+      # @example With options
+      #   MyAgent.prompt(message: "Hello", temperature: 0.8).generate_now
+      def prompt(*messages, **options)
+        ActiveAgent::Parameterized::DirectGeneration.new(self, :prompt, {}, *messages, **options)
+      end
+
+      # Creates a direct embed generation without defining an action method.
+      #
+      # This allows you to generate embeddings inline without needing to define
+      # an action method on the agent class.
+      #
+      # @param input [String, Array<String>, nil] text to embed
+      # @param options [Hash] parameters to merge into embedding context
+      # @return [ActiveAgent::Parameterized::Generation] a generation instance
+      #   ready for embed_now, embed_later, etc.
+      #
+      # @example Direct embedding
+      #   MyAgent.embed(input: "Text to embed").embed_now
+      #
+      # @example With array input
+      #   MyAgent.embed(input: ["First", "Second"]).embed_now
+      #
+      # @example With options
+      #   MyAgent.embed(input: "Text", model: "text-embedding-3-large").embed_now
+      def embed(input = nil, **options)
+        ActiveAgent::Parameterized::DirectGeneration.new(self, :embed, {}, input, **options)
+      end
+    end
+
+    # Proxy class that intercepts method calls to create parameterized generations.
+    #
+    # This class is returned by {ClassMethods#with} and acts as a proxy to the
+    # actual agent class, capturing method calls to actions and creating
+    # {Generation} instances with the stored parameters.
+    #
+    # @api private
+    class Agent
+      # @param agent [Class] the agent class to proxy
+      # @param params [Hash] the parameters to pass to agent instances
+      def initialize(agent, params)
+        @agent = agent
+        @params = params
+      end
+
+      # Intercepts calls to agent action methods and creates parameterized generations.
+      #
+      # @param method_name [Symbol] the name of the action method being called
+      # @param args [Array] arguments to pass to the action method
+      # @return [ActiveAgent::Parameterized::Generation] a generation
+      #   instance with the stored parameters
+      # @raise [NoMethodError] if the method doesn't exist on the agent class
+      def method_missing(method_name, ...)
+        if @agent.public_instance_methods.include?(method_name)
+          ActiveAgent::Parameterized::Generation.new(@agent, method_name, @params, ...)
+        else
+          super
+        end
+      end
+
+      # @param method [Symbol] the method name to check
+      # @param include_all [Boolean] whether to include private and protected methods
+      # @return [Boolean] true if the agent responds to the method
+      def respond_to_missing?(method, include_all = false)
+        @agent.respond_to?(method, include_all)
+      end
+    end
+
+    # A specialized generation class that handles parameterized agent actions.
+    #
+    # This class extends {ActiveAgent::Generation} to support passing parameters
+    # to agent instances before processing actions. It ensures parameters are
+    # properly set both for immediate processing and when enqueuing background jobs.
+    #
+    # @api private
+    class Generation < ActiveAgent::Generation
+      # @param agent_class [Class] the agent class
+      # @param action [Symbol, String] the action method name
+      # @param params [Hash] the parameters to set on the agent instance
+      # @param args [Array] additional arguments for the action method
+      def initialize(agent_class, action, params, ...)
+        super(agent_class, action, ...)
+        @params = params
+      end
+
+      private
+
+      # Creates and processes an agent instance with parameters set.
+      #
+      # @return [ActiveAgent::Base] the processed agent instance with params
+      def agent
+        @agent ||= agent_class.new.tap do |agent|
+          agent.params = @params
+          agent.process(action_name, *args, **kwargs)
+        end
+      end
+
+      # Enqueues a generation job with parameters included.
+      #
+      # This method ensures that when a parameterized generation is enqueued,
+      # the parameters are passed to the background job so they can be
+      # properly set when the job executes.
+      #
+      # @param generation_method [Symbol, String] the generation method to call
+      # @param job_options [Hash] options to pass to the job (e.g., queue, priority)
+      # @return [Object] the enqueued job instance
+      def enqueue_generation(generation_method, job_options = {})
+        if processed?
+          super
+        else
+          agent_class.generation_job.set(job_options).perform_later(
+            agent_class.name, action_name.to_s, generation_method.to_s, params: @params, args: args, kwargs: kwargs
+          )
+        end
+      end
+    end
+
+    # A specialized generation class for direct prompt/embed calls without actions.
+    #
+    # This class handles cases where you want to call Agent.prompt(...).generate_now
+    # or Agent.embed(...).generate_now without defining an action method.
+    #
+    # @api private
+    class DirectGeneration < Generation
+      # @param agent_class [Class] the agent class
+      # @param generation_type [Symbol] either :prompt or :embed
+      # @param params [Hash] the parameters to set on the agent instance
+      # @param args [Array] messages for prompt or input for embed
+      # @param options [Hash] additional options (temperature, model, etc.)
+      def initialize(agent_class, generation_type, params, *args, **options)
+        @generation_type = generation_type
+        @direct_args = args
+        @direct_options = options
+
+        # Use a synthetic action name that won't conflict with real methods
+        super(agent_class, :"__direct_#{generation_type}__", params)
+      end
+
+      # Override generate_now to route to correct method based on generation type
+      def generate_now
+        case @generation_type
+        when :prompt
+          prompt_now
+        when :embed
+          embed_now
+        end
+      end
+
+      # Override generate_now! to route to correct method based on generation type
+      def generate_now!
+        case @generation_type
+        when :prompt
+          prompt_now!
+        when :embed
+          # For embed, we don't have a separate embed_now! method, so use embed_now
+          embed_now
+        end
+      end
+
+      # Generates a preview based on generation type.
+      #
+      # @return [String] markdown-formatted preview for prompt generations
+      # @raise [NotImplementedError] for embed generations (not yet supported)
+      def preview
+        case @generation_type
+        when :prompt
+          prompt_preview
+        when :embed
+          raise NotImplementedError, "Embed previewing is not supported"
+        end
+      end
+
+      private
+
+      # Creates and processes an agent instance for direct generation.
+      #
+      # Instead of calling a real action method, this directly calls the
+      # prompt() or embed() method on the agent instance with the provided arguments.
+      #
+      # @return [ActiveAgent::Base] the processed agent instance
+      def agent
+        @agent ||= agent_class.new.tap do |agent|
+          agent.params = @params
+
+          # Directly call prompt or embed method instead of processing an action
+          case @generation_type
+          when :prompt
+            agent.send(:prompt, *@direct_args, **@direct_options)
+          when :embed
+            agent.send(:embed, *@direct_args, **@direct_options)
+          end
+        end
+      end
+
+      # Enqueues a direct generation job.
+      #
+      # @param generation_method [Symbol, String] the generation method to call
+      # @param job_options [Hash] options to pass to the job
+      # @return [Object] the enqueued job instance
+      def enqueue_generation(generation_method, job_options = {})
+        if processed?
+          super
+        else
+          # For direct generations, we need to store the generation type and options
+          agent_class.generation_job.set(job_options).perform_later(
+            agent_class.name,
+            action_name.to_s,
+            generation_method.to_s,
+            params: @params,
+            args: args,
+            kwargs: kwargs,
+            direct_generation_type: @generation_type,
+            direct_args: @direct_args,
+            direct_options: @direct_options
+          )
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/concerns/provider.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../providers/_base_provider"
+
+module ActiveAgent
+  # Configures and manages AI provider integration for action prompts.
+  module Provider
+    extend ActiveSupport::Concern
+
+    # "Your tacky and I hate you" - Billy, https://youtu.be/dsheboxJNgQ?si=tzDlJ7sdSxM4RjSD
+    PROVIDER_SERVICE_NAMES_REMAPS = {
+      "Openrouter" => "OpenRouter",
+      "Openai"     => "OpenAI"
+    }
+
+    included do
+      class_attribute :_prompt_provider_klass, instance_accessor: false, instance_predicate: false
+      class_attribute :_embed_provider_klass,  instance_accessor: false, instance_predicate: false
+
+      delegate :prompt_provider_klass, :embed_provider_klass, to: :class
+    end
+
+    class_methods do
+      # Sets the prompt provider for this class.
+      #
+      # @param reference [Symbol, String, ActiveAgent::Provider::BaseProvider, Anthropic::Client, OpenAI::Client]
+      #   Provider identifier, instance, or client
+      # @raise [ArgumentError] if reference type is unsupported
+      # @return [void]
+      def prompt_provider=(reference)
+        case reference
+        when Symbol, String
+          self._prompt_provider_klass = configuration(reference)
+
+        when ActiveAgent::Providers::BaseProvider
+          self._prompt_provider_klass = reference
+
+        when ->(ref) { defined?(::Anthropic) && ref.is_a?(::Anthropic::Client) }
+          self._prompt_provider_klass = provider_load("Anthropic")
+
+        when ->(ref) { defined?(::OpenAI) && ref.is_a?(::OpenAI::Client) }
+          self._prompt_provider_klass = provider_load("OpenAI")
+        else
+          raise ArgumentError
+        end
+      end
+
+      # Sets the embed provider for this class.
+      #
+      # @param reference [Symbol, String, ActiveAgent::Provider::BaseProvider, Anthropic::Client, OpenAI::Client]
+      #   Provider identifier, instance, or client
+      # @raise [ArgumentError] if reference type is unsupported
+      # @return [void]
+      def embed_provider=(reference)
+        case reference
+        when Symbol, String
+          self._embed_provider_klass = configuration(reference)
+
+        when ActiveAgent::Providers::BaseProvider
+          self._embed_provider_klass = reference
+
+        when ->(ref) { defined?(::OpenAI) && ref.is_a?(::OpenAI::Client) }
+          self._embed_provider_klass = provider_load("OpenAI")
+        else
+          raise ArgumentError
+        end
+      end
+
+      # Loads provider class from configuration.
+      #
+      # @param reference [Symbol, String] Provider identifier
+      # @param options [Hash] Additional configuration options
+      # @return [Class] Provider class
+      # @raise [RuntimeError] if provider fails to load
+      def provider_setup(reference, **options)
+        type   = reference.to_sym
+        config = { service: type.to_s.camelize }.merge(provider_config_load(type)).merge(options)
+        provider_load(config[:service])
+
+      rescue LoadError => e
+        raise RuntimeError, "Failed to load provider #{type}: #{e.message}"
+      end
+      alias configuration provider_setup
+
+      # Retrieves provider configuration.
+      #
+      # @param provider_type [Symbol, String] Provider identifier
+      # @return [Hash] Configuration hash with symbolized keys
+      def provider_config_load(provider_type)
+        path = [ ENV["RAILS_ENV"], provider_type.to_s ].compact
+
+        path.length.downto(1).map do |index|
+          ActiveAgent.configuration.dig(*path[(path.length - index)..])
+        end.compact.first&.deep_symbolize_keys || {}
+      end
+
+      # Loads provider class by service name.
+      #
+      # @param service_name [String] Service name (e.g., "OpenAI", "Anthropic")
+      # @return [Class] Provider class
+      def provider_load(service_name)
+        require "active_agent/providers/#{service_name.underscore}_provider"
+
+        service_name = Hash.new(service_name).merge!(PROVIDER_SERVICE_NAMES_REMAPS)[service_name]
+
+        ActiveAgent::Providers.const_get("#{service_name.camelize}Provider")
+      end
+
+      # Returns the configured prompt provider class.
+      #
+      # @return [Class, nil] Prompt provider class if set
+      def prompt_provider_klass = _prompt_provider_klass
+
+      # Returns the configured embed provider class.
+      #
+      # @return [Class, nil] Embed provider class if set
+      def embed_provider_klass = _embed_provider_klass
+    end
+  end
+end

data/lib/active_agent/concerns/queueing.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  # Configures asynchronous generation via Active Job.
+  #
+  # Provides class attributes to customize which job class processes
+  # queued generations and which queue they run on. Enables agents to
+  # defer prompt generation and embedding operations for background processing.
+  #
+  # @example Custom job class
+  #   class MyAgent < ActiveAgent::Base
+  #     self.generation_job = CustomGenerationJob
+  #   end
+  #
+  # @example Custom queue name
+  #   class PriorityAgent < ActiveAgent::Base
+  #     self.generate_later_queue_name = :high_priority
+  #   end
+  #
+  # @see ActiveAgent::GenerationJob
+  module Queueing
+    extend ActiveSupport::Concern
+
+    included do
+      # Job class used to process queued generations.
+      #
+      # @return [Class] defaults to ActiveAgent::GenerationJob
+      class_attribute :generation_job, default: ::ActiveAgent::GenerationJob
+
+      # Queue name for generation jobs.
+      #
+      # @return [Symbol] defaults to :agents
+      class_attribute :generate_later_queue_name, default: :agents
+    end
+  end
+end

data/lib/active_agent/concerns/rescue.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  # Provides exception handling for action prompts using `rescue_from` declarations.
+  #
+  # Handler methods must be public or protected because ActiveSupport::Rescuable
+  # uses `Kernel#method()` for lookup.
+  #
+  # @see https://github.com/rails/rails/blob/main/actionpack/lib/action_controller/metal/rescue.rb
+  # @see ActiveSupport::Rescuable
+  module Rescue
+    extend ActiveSupport::Concern
+    include ActiveSupport::Rescuable
+
+    class_methods do
+      # Finds and instruments the rescue handler for an exception.
+      #
+      # @param exception [Exception] the exception to handle
+      # @return [Proc, nil] the handler proc if found, nil otherwise
+      # @api private
+      # def handler_for_rescue(exception, ...)
+      #   if (handler = super)
+      #     ActiveSupport::Notifications.instrument("rescue_from_callback.active_agent", exception:)
+      #     handler
+      #   end
+      # end
+    end
+
+    # Yields to block with exception handling.
+    # Rescues using registered handlers or re-raises.
+    #
+    # @yield block to execute with exception handling
+    # @raise [Exception] if no handler is registered for the exception
+    def handle_exceptions
+      yield
+    rescue Exception => exception
+      rescue_with_handler(exception) || raise
+    end
+
+    private
+
+    # Processes the prompt with exception handling.
+    #
+    # Overrides parent to rescue exceptions using registered handlers.
+    #
+    # @raise [Exception] if no handler is registered for the exception
+    # @api private
+    def process(...)
+      super
+    rescue Exception => exception
+      rescue_with_handler(exception) || raise
+    end
+
+    # Returns proc that rescues exceptions using registered handlers.
+    #
+    # @return [Proc]
+    # @api private
+    def exception_handler
+      proc do |exception|
+        rescue_with_handler(exception)
+      end
+    end
+  end
+end