activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/base.rb

@@ -1,46 +1,396 @@
 # frozen_string_literal: true
 
-require "active_agent/action_prompt"
-require "active_agent/prompt_helper"
-require "active_agent/action_prompt/base"
-
-# The ActiveAgent module provides a framework for creating agents that can generate content
-# and handle various actions. The Base class within this module extends AbstractController::Base
-# and includes several modules to provide additional functionality such as callbacks, generation
-# methods, and rescuable actions.
-#
-# The Base class defines several class methods for registering and unregistering observers and
-# interceptors, as well as methods for generating content with a specified provider and streaming
-# content. It also provides methods for setting default parameters and handling prompts.
-#
-# The instance methods in the Base class include methods for performing generation, processing
-# actions, and handling headers and attachments. The class also defines a NullPrompt class for
-# handling cases where no prompt is provided.
-#
-# The Base class uses ActiveSupport::Notifications for instrumentation and provides several
-# private methods for setting payloads, applying defaults, and collecting responses from blocks,
-# text, or templates.
-#
-# The class also includes several protected instance variables and defines hooks for loading
-# additional functionality.
+require "active_support/core_ext/hash/except"
+require "active_support/core_ext/module/anonymous"
+require "active_support/core_ext/string/inflections"
+
+require "active_agent/concerns/callbacks"
+require "active_agent/concerns/observers"
+require "active_agent/concerns/parameterized"
+require "active_agent/concerns/preview"
+require "active_agent/concerns/provider"
+require "active_agent/concerns/queueing"
+require "active_agent/concerns/rescue"
+require "active_agent/concerns/streaming"
+require "active_agent/concerns/tooling"
+require "active_agent/concerns/view"
+
+require "active_agent/providers/log_subscriber"
+
 module ActiveAgent
-  class Base < ActiveAgent::ActionPrompt::Base
-    # This class is the base class for agents in the ActiveAgent framework.
-    # It is built on top of ActionPrompt which provides methods for generating content, handling actions, and managing prompts.
-    # ActiveAgent::Base is designed to be extended by specific agent implementations.
-    # It provides a common set of agent actions for self-contained agents that can determine their own actions using all available actions.
-    # Base actions include: prompt_context, continue, reasoning, reiterate, and conclude
-    def prompt_context(additional_options = {})
-      prompt(
-        {
-          stream: params[:stream],
-          messages: params[:messages],
-          message: params[:message],
-          context_id: params[:context_id],
-          options: params[:options],
-          mcp_servers: params[:mcp_servers]
-        }.merge(additional_options)
+  # Provides AI-powered agents with prompt generation, tool calling, and conversation management.
+  #
+  # @example Basic agent
+  #   class MyAgent < ActiveAgent::Base
+  #     generate_with :openai, model: "gpt-4"
+  #
+  #     def greet
+  #       prompt instructions: "Greet the user warmly"
+  #     end
+  #   end
+  #
+  # @abstract
+  class Base < AbstractController::Base
+    abstract!
+
+    include AbstractController::Rendering
+    include AbstractController::Logger
+    include AbstractController::Helpers
+    include AbstractController::Translation
+    include AbstractController::AssetPaths
+    include AbstractController::Callbacks
+    include AbstractController::Caching
+
+    include Callbacks
+    include Parameterized
+    include Provider
+    include Queueing
+    include Rescue
+    include Streaming
+    include Tooling
+    include View
+
+    include Observers
+    include Previews
+
+    PROTECTED_OPTIONS = %i[exception_handler stream_broadcaster tools_function]
+    PROTECTED_IVARS = AbstractController::Rendering::DEFAULT_PROTECTED_INSTANCE_VARIABLES + [ :@_action_has_layout ]
+
+    # Logger instance for agent operations.
+    #
+    # Defaults to Rails.logger when used in Rails applications.
+    # Must conform to Log4r or Ruby Logger interface.
+    #
+    # @return [Logger, nil]
+    cattr_accessor :logger
+
+    class_attribute :prompt_options
+    class_attribute :embed_options
+
+    class << self
+      class_attribute :default_params, default: {
+        mime_version: "1.0",
+        charset: "UTF-8",
+        content_type: "text/plain",
+        parts_order: [ "text/markdown", "text/plain", "text/enriched", "text/html" ]
+      }.freeze
+
+      # Sets default parameters applied to all actions unless overridden.
+      #
+      # @param value [Hash, nil] parameters to merge, or nil to return current defaults
+      # @return [Hash]
+      #
+      # @example
+      #   default temperature: 0.7, max_tokens: 1000
+      def default(value = nil)
+        self.default_params = default_params.merge(value).freeze if value
+        default_params
+      end
+      alias_method :default_params=, :default
+    end
+
+    # Configures generation provider and options for prompt generation.
+    #
+    # Options are merged with global provider config and inherited parent class options.
+    # Instructions are never inherited from parent classes.
+    #
+    # @param provider_reference [Symbol, String] generation provider (:openai, :anthropic, etc.)
+    # @param agent_options [Hash] configuration options shared across actions
+    # @return [void]
+    #
+    # @example
+    #   generate_with :openai, model: "gpt-4", temperature: 0.7
+    def self.generate_with(provider_reference, **agent_options)
+      self.prompt_provider = provider_reference
+
+      global_options    = provider_config_load(provider_reference)
+      inherited_options = (self.prompt_options || {}).except(:instructions) # Don't inherit instructions from parent
+
+      # Different Service, different APIs
+      if global_options[:service] != inherited_options[:service]
+        inherited_options.extract!(:service, :api_version)
+      end
+
+      self.prompt_options = global_options.merge(inherited_options).merge(agent_options)
+    end
+
+    # Configures embedding provider and options for embedding generation.
+    #
+    # @param provider_reference [Symbol, String] embedding provider (:openai, :anthropic, etc.)
+    # @param agent_options [Hash] configuration options for embedding generation
+    # @return [void]
+    #
+    # @example
+    #   embed_with :openai, model: "text-embedding-3-large"
+    def self.embed_with(provider_reference, **agent_options)
+      self.embed_provider = provider_reference
+
+      global_options    = provider_config_load(provider_reference)
+      inherited_options = self.embed_options || {}
+
+      self.embed_options = global_options.merge(inherited_options).merge(agent_options)
+    end
+
+    # @api private
+    def self.method_missing(method_name, ...)
+      if action_methods.include?(method_name.name)
+        Generation.new(self, method_name, ...)
+      else
+        super
+      end
+    end
+    private_class_method :method_missing
+
+    # @api private
+    def self.respond_to_missing?(method, include_all = false)
+      action_methods.include?(method.name) || super
+    end
+    private_class_method :respond_to_missing?
+
+    delegate :agent_name, to: :class
+
+    # @!attribute [w] agent_name
+    # Agent name override for custom view lookup paths.
+    # @return [String]
+    attr_writer :agent_name
+    alias_method :controller_path, :agent_name
+
+    # @!attribute [rw] prompt_options
+    # Action-level prompt options merged with agent prompt options.
+    # @return [Hash]
+    attr_internal :prompt_options
+
+    # @!attribute [rw] embed_options
+    # Action-level embed options merged with agent embed options.
+    # @return [Hash]
+    attr_internal :embed_options
+
+    # @api private
+    def initialize # :nodoc:
+      super
+      self.prompt_options = (self.class.prompt_options&.deep_dup || {}).except(:trace_id)
+      self.embed_options  = (self.class.embed_options&.deep_dup  || {}).except(:trace_id)
+    end
+
+    # Agent name used as a path for view lookup.
+    #
+    # @return [String] agent name or "anonymous" for anonymous agents
+    def agent_name
+      @agent_name ||= self.class.anonymous? ? "anonymous" : self.class.name.underscore
+    end
+
+    # Processes an agent action with ActiveSupport::Notifications instrumentation.
+    #
+    # Actions are triggered externally via Agent.action_name.generate_now or internally
+    # through tool calls during AI generation workflows.
+    #
+    # @param method_name [Symbol, String] action method to process
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [void]
+    # @api private
+    def process(method_name, *args, **kwargs)
+      payload = { agent: self.class.name, action: method_name, args:, kwargs: }
+
+      ActiveSupport::Notifications.instrument("process.active_agent", payload) do
+        super
+      end
+    end
+
+    # Merges action-level parameters into prompt context.
+    #
+    # Processing is deferred until execution to allow local overrides.
+    #
+    # @param messages [Array<String, Hash>] message strings or hashes to add to conversation
+    # @param options [Hash] parameters to merge into prompt context
+    # @return [void]
+    #
+    # @example
+    #   def my_action
+    #     prompt "User message", temperature: 0.8, instructions: "Be creative"
+    #   end
+    def prompt(*messages, **options)
+      # Extract message/messages from options and add to messages array
+      messages += options.extract!(:message, :messages).values.flatten.compact
+
+      # Extract image and document attachments
+      messages += options.extract!(:image, :document).map { |k, v| { k => v } }
+
+      prompt_options.merge!({ messages: }.compact_blank.merge!(options))
+    end
+
+    # Merges action-level parameters into embedding context.
+    #
+    # @param input [String, Array<String>, nil] text to embed
+    # @param options [Hash] parameters to merge into embedding context
+    # @return [void]
+    #
+    # @example With direct input
+    #   embed "Text to embed", model: "text-embedding-3-large"
+    #
+    # @example With template
+    #   embed locals: { text: "Custom text" }
+    def embed(input = nil, **options)
+      new_options = { input: }.compact_blank.merge!(options)
+      embed_options.merge!(new_options)
+    end
+
+    # Executes prompt generation using configured provider and options.
+    #
+    # Triggered by generate_now or generate_later workflows. Templates are
+    # rendered as late as possible to allow local overrides.
+    #
+    # @return [ActiveAgent::Providers::Response]
+    # @raise [RuntimeError] if no prompt provider is configured
+    def process_prompt
+      fail "Prompt Provider not Configured" unless prompt_provider_klass
+
+      run_callbacks(:generation) do
+        run_callbacks(:prompting) do
+          parameters = prepare_prompt_parameters
+
+          prompt_provider_klass.new(**parameters).prompt
+        end
+      end
+    end
+
+    alias_method :process_prompt!, :process_prompt
+
+    # Generates a preview of the prompt without executing generation.
+    #
+    # Useful for debugging and inspecting the final prompt that would be
+    # sent to the provider, including rendered templates and merged parameters.
+    #
+    # @return [String, Hash] preview format depends on provider implementation
+    # @raise [RuntimeError] if no prompt provider is configured
+    def preview_prompt
+      fail "Prompt Provider not Configured" unless prompt_provider_klass
+
+      parameters = prepare_prompt_parameters
+
+      prompt_provider_klass.new(**parameters).preview
+    end
+
+    # Executes embedding generation using configured provider and options.
+    #
+    # Templates are rendered as late as possible to allow local overrides.
+    #
+    # @return [ActiveAgent::Providers::Response]
+    # @raise [RuntimeError] if no embed provider is configured
+    def process_embed
+      fail "Embed Provider not Configured" unless embed_provider_klass
+
+      run_callbacks(:generation) do
+        run_callbacks(:embedding) do
+          parameters = prepare_embed_parameters
+
+          embed_provider_klass.new(**parameters).embed
+        end
+      end
+    end
+
+    # @api private
+    def action_methods
+      super - ActiveAgent::Base.public_instance_methods(false).map(&:to_s) - [ action_name ]
+    end
+
+    private
+
+    # @api private
+    def prepare_prompt_parameters
+      parameters = prompt_options.deep_dup.except(:locals, *PROTECTED_OPTIONS)
+
+      # Render out proc/lamda attributes before rendering templates
+      parameters.deep_transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
+
+      # Apply Callbacks
+      parameters.merge!(
+        trace_id: prompt_options[:trace_id] || SecureRandom.uuid,
+        exception_handler:,
+        stream_broadcaster:,
+        tools_function:,
       )
+
+      # Apply Templates
+      parameters = process_prompt_templates(parameters, prompt_options)
+
+      parameters.compact
+    end
+
+    # @api private
+    def prepare_embed_parameters
+      parameters = embed_options.deep_dup.except(:locals, *PROTECTED_OPTIONS)
+
+      # Render out proc/lamda attributes before rendering templates
+      parameters.deep_transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
+
+      # Apply Callbacks
+      parameters.merge!(
+        trace_id: prompt_options[:trace_id] || SecureRandom.uuid,
+        exception_handler:
+      ).compact!
+
+      # Fallback to input from template if no input provided, rendered as late as
+      # possible to allow local overrides.
+      if parameters[:input].blank?
+        template_input = embed_view_input(action_name, strict: true, **(embed_options[:locals] || {}))
+        parameters[:input] = template_input if template_input.present?
+      end
+
+      parameters.compact
     end
+
+    # @api private
+    def process_prompt_templates(parameters, prompt_options)
+      # Resolve Instructions
+      parameters[:instructions] = prompt_view_instructions(parameters[:instructions])
+
+      # Resolve Message Template as fallback
+      if (parameters[:messages] || parameters[:input]).blank?
+        template_message = prompt_view_message(action_name, strict: parameters[:instructions].blank?, **(prompt_options[:locals] || {}))
+        parameters[:messages] = [ template_message ] if template_message.present?
+      end
+
+      # Resolve Response Format
+      if parameters[:response_format]
+        parameters[:response_format] = process_prompt_templates_response_format(parameters[:response_format])
+      end
+
+      parameters
+    end
+
+    # @api private
+    def process_prompt_templates_response_format(response_format)
+      if response_format.is_a?(Symbol) || response_format.is_a?(String)
+        response_format = { type: response_format.to_s }
+      end
+
+      if response_format[:type].to_sym == :json_schema
+        response_format[:json_schema] = prompt_view_schema(response_format[:json_schema])
+        response_format[:json_schema].deep_transform_keys! { _1.to_s.camelize(:lower) }
+      end
+
+      response_format
+    end
+
+    # @api private
+    def instrument_payload(key)
+      {
+        agent: agent_name,
+        key: key
+      }
+    end
+
+    # @api private
+    def instrument_name
+      "active_agent"
+    end
+
+    # @api private
+    def _protected_ivars
+      PROTECTED_IVARS
+    end
+
+    ActiveSupport.run_load_hooks(:active_agent, self)
   end
 end

data/lib/active_agent/concerns/callbacks.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "active_support/callbacks"
+
+module ActiveAgent
+  # Provides callback hooks for generation, prompting, and embedding lifecycles.
+  #
+  # Enables agents to execute custom logic before, after, or around AI operations.
+  # Callbacks support conditional execution via `:if` and `:unless` options, and
+  # after callbacks are skipped when the chain is terminated with `throw :abort`.
+  #
+  # == Callback Types
+  #
+  # Each lifecycle supports three timing hooks:
+  # * +before_*+ - executes before the operation
+  # * +after_*+ - executes after the operation (skipped if aborted)
+  # * +around_*+ - wraps the operation (must call +yield+)
+  #
+  # == Lifecycle Hierarchies
+  #
+  # * +generation+ - wraps both prompting and embedding operations
+  # * +prompting+ - specific to prompt execution
+  # * +embedding+ - specific to embedding operations
+  #
+  # Use +*_generation+ callbacks for cross-cutting concerns like rate limiting,
+  # authentication, and logging that apply to all AI operations.
+  #
+  # == Callback Control
+  #
+  # * +prepend_*+ - inserts callback at the beginning of the chain
+  # * +append_*+ - adds callback at the end (same as base methods)
+  # * +skip_*+ - removes a previously defined callback
+  #
+  # @example Rate limiting with generation callbacks
+  #   class MyAgent < ActiveAgent::Base
+  #     before_generation :check_rate_limit
+  #     after_generation :record_usage
+  #
+  #     def check_rate_limit
+  #       raise RateLimitExceeded if RateLimiter.exceeded?(user_id)
+  #     end
+  #
+  #     def record_usage
+  #       RateLimiter.increment(user_id)
+  #     end
+  #   end
+  #
+  # @example Before prompting callback
+  #   class MyAgent < ActiveAgent::Base
+  #     before_prompt :load_context
+  #
+  #     def load_context
+  #       @user_data = User.find(params[:user_id])
+  #     end
+  #   end
+  #
+  # @example After prompting with condition
+  #   class MyAgent < ActiveAgent::Base
+  #     after_prompt :log_response, if: :production?
+  #
+  #     def log_response
+  #       Logger.info("Generated response: #{context.messages.last}")
+  #     end
+  #   end
+  #
+  # @example Around embedding for timing
+  #   class MyAgent < ActiveAgent::Base
+  #     around_embed :measure_time
+  #
+  #     def measure_time
+  #       start = Time.now
+  #       yield
+  #       Rails.logger.info("Embedding took #{Time.now - start}s")
+  #     end
+  #   end
+  #
+  # @example Prepending and skipping callbacks
+  #   class MyAgent < ActiveAgent::Base
+  #     prepend_before_prompt :urgent_check  # Runs first
+  #     before_prompt :normal_check          # Runs second
+  #
+  #     skip_after_prompt :log_response      # Removes inherited callback
+  #   end
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveSupport::Callbacks
+      define_callbacks :generation, skip_after_callbacks_if_terminated: true
+      define_callbacks :prompting,  skip_after_callbacks_if_terminated: true
+      define_callbacks :embedding,  skip_after_callbacks_if_terminated: true
+    end
+
+    module ClassMethods
+      # Registers callbacks for the prompting lifecycle.
+      #
+      # Dynamically defines callback methods for each timing hook.
+      # Multiple callbacks execute in registration order for before/around,
+      # and reverse order for after.
+      #
+      # @param names [Symbol, Array<Symbol>] method name(s) to call
+      # @param blk [Proc] optional block to execute instead of named method
+      # @yield callback implementation when using block form
+      #
+      # @example Multiple before callbacks
+      #   before_prompt :load_user, :check_permissions
+      #
+      # @example Block syntax
+      #   after_prompt do
+      #     cache.write("last_response", context.messages.last)
+      #   end
+      [ :before, :after, :around ].each do |callback|
+        define_method "#{callback}_prompt" do |*names, &blk|
+          _insert_callbacks(names, blk) do |name, options|
+            set_callback(:prompting, callback, name, options)
+          end
+        end
+
+        # Prepends a callback to the beginning of the prompting chain.
+        #
+        # Useful for ensuring critical setup runs before other callbacks.
+        #
+        # @param names [Symbol, Array<Symbol>] method name(s) to call
+        # @param blk [Proc] optional block to execute
+        #
+        # @example Prepend urgent validation
+        #   prepend_before_prompt :validate_api_key
+        define_method "prepend_#{callback}_prompt" do |*names, &blk|
+          _insert_callbacks(names, blk) do |name, options|
+            set_callback(:prompting, callback, name, options.merge(prepend: true))
+          end
+        end
+
+        # Skips a previously defined prompting callback.
+        #
+        # Useful for removing inherited callbacks or disabling callbacks
+        # conditionally in subclasses.
+        #
+        # @param names [Symbol, Array<Symbol>] method name(s) to skip
+        #
+        # @example Skip inherited callback
+        #   skip_after_prompt :log_response
+        define_method "skip_#{callback}_prompt" do |*names|
+          _insert_callbacks(names) do |name, options|
+            skip_callback(:prompting, callback, name, options)
+          end
+        end
+
+        # Alias for explicit append behavior (same as base method).
+        alias_method :"append_#{callback}_prompt", :"#{callback}_prompt"
+
+        # Registers callbacks for the generation lifecycle.
+        #
+        # Generation callbacks wrap both prompting and embedding operations,
+        # making them ideal for cross-cutting concerns like rate limiting,
+        # authentication, logging, and resource management that apply to all
+        # AI operations.
+        #
+        # @param names [Symbol, Array<Symbol>] method name(s) to call
+        # @param blk [Proc] optional block to execute instead of named method
+        # @yield callback implementation when using block form
+        #
+        # @example Rate limiting for all operations
+        #   before_generation :check_rate_limit
+        #   after_generation :record_usage
+        #
+        # @example Authentication check
+        #   around_generation :with_api_key
+        define_method "#{callback}_generation" do |*names, &blk|
+          _insert_callbacks(names, blk) do |name, options|
+            set_callback(:generation, callback, name, options)
+          end
+        end
+
+        # Prepends a callback to the beginning of the generation chain.
+        #
+        # @param names [Symbol, Array<Symbol>] method name(s) to call
+        # @param blk [Proc] optional block to execute
+        #
+        # @example Prepend rate limiting
+        #   prepend_before_generation :check_rate_limit
+        define_method "prepend_#{callback}_generation" do |*names, &blk|
+          _insert_callbacks(names, blk) do |name, options|
+            set_callback(:generation, callback, name, options.merge(prepend: true))
+          end
+        end
+
+        # Skips a previously defined generation callback.
+        #
+        # @param names [Symbol, Array<Symbol>] method name(s) to skip
+        #
+        # @example Skip inherited callback
+        #   skip_before_generation :check_rate_limit
+        define_method "skip_#{callback}_generation" do |*names|
+          _insert_callbacks(names) do |name, options|
+            skip_callback(:generation, callback, name, options)
+          end
+        end
+
+        # Alias for explicit append behavior (same as base method).
+        alias_method :"append_#{callback}_generation", :"#{callback}_generation"
+
+        # Registers callbacks for the embedding lifecycle.
+        #
+        # Behavior identical to prompting callbacks but invoked during
+        # embedding operations.
+        #
+        # @param names [Symbol, Array<Symbol>] method name(s) to call
+        # @param blk [Proc] optional block to execute instead of named method
+        # @yield callback implementation when using block form
+        #
+        # @example Track embedding calls
+        #   before_embed :increment_counter
+        #   after_embed :store_embedding
+        define_method "#{callback}_embed" do |*names, &blk|
+          _insert_callbacks(names, blk) do |name, options|
+            set_callback(:embedding, callback, name, options)
+          end
+        end
+
+        # Prepends a callback to the beginning of the embedding chain.
+        #
+        # @param names [Symbol, Array<Symbol>] method name(s) to call
+        # @param blk [Proc] optional block to execute
+        #
+        # @example Prepend rate limiting
+        #   prepend_before_embed :check_rate_limit
+        define_method "prepend_#{callback}_embed" do |*names, &blk|
+          _insert_callbacks(names, blk) do |name, options|
+            set_callback(:embedding, callback, name, options.merge(prepend: true))
+          end
+        end
+
+        # Skips a previously defined embedding callback.
+        #
+        # @param names [Symbol, Array<Symbol>] method name(s) to skip
+        #
+        # @example Skip inherited callback
+        #   skip_before_embed :validate_input
+        define_method "skip_#{callback}_embed" do |*names|
+          _insert_callbacks(names) do |name, options|
+            skip_callback(:embedding, callback, name, options)
+          end
+        end
+
+        # Alias for explicit append behavior (same as base method).
+        alias_method :"append_#{callback}_embed", :"#{callback}_embed"
+      end
+    end
+  end
+end