activeagent 0.0.0 → 0.1.0

data/lib/active_agent/base.rb

@@ -0,0 +1,439 @@
+# frozen_string_literal: true
+
+require "active_agent/prompt_helper"
+require "active_agent/action_prompt/prompt"
+require "active_agent/action_prompt/collector"
+require "active_support/core_ext/string/inflections"
+require "active_support/core_ext/hash/except"
+require "active_support/core_ext/module/anonymous"
+
+# require "active_agent/log_subscriber"
+require "active_agent/rescuable"
+
+# 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.
+module ActiveAgent
+  class Base < AbstractController::Base
+    include Callbacks
+    include GenerationMethods
+    include GenerationProvider
+    include QueuedGeneration
+    include Rescuable
+    include Parameterized
+    include Previews
+    # include FormBuilder
+
+    abstract!
+
+    include AbstractController::Rendering
+
+    include AbstractController::Logger
+    include AbstractController::Helpers
+    include AbstractController::Translation
+    include AbstractController::AssetPaths
+    include AbstractController::Callbacks
+    include AbstractController::Caching
+
+    include ActionView::Layouts
+
+    PROTECTED_IVARS = AbstractController::Rendering::DEFAULT_PROTECTED_INSTANCE_VARIABLES + [:@_action_has_layout]
+
+    helper ActiveAgent::PromptHelper
+
+    class_attribute :options
+
+    class_attribute :default_params, default: {
+      mime_version: "1.0",
+      charset: "UTF-8",
+      content_type: "text/plain",
+      parts_order: ["text/plain", "text/enriched", "text/html"]
+    }.freeze
+
+    class << self
+      def prompt(...)
+        new.prompt(...)
+      end
+
+      # Register one or more Observers which will be notified when mail is delivered.
+      def register_observers(*observers)
+        observers.flatten.compact.each { |observer| register_observer(observer) }
+      end
+
+      # Unregister one or more previously registered Observers.
+      def unregister_observers(*observers)
+        observers.flatten.compact.each { |observer| unregister_observer(observer) }
+      end
+
+      # Register one or more Interceptors which will be called before mail is sent.
+      def register_interceptors(*interceptors)
+        interceptors.flatten.compact.each { |interceptor| register_interceptor(interceptor) }
+      end
+
+      # Unregister one or more previously registered Interceptors.
+      def unregister_interceptors(*interceptors)
+        interceptors.flatten.compact.each { |interceptor| unregister_interceptor(interceptor) }
+      end
+
+      # Register an Observer which will be notified when mail is delivered.
+      # 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.
+      def register_observer(observer)
+        Mail.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.
+      def unregister_observer(observer)
+        Mail.unregister_observer(observer_class_for(observer))
+      end
+
+      # Register an Interceptor which will be called before mail 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.
+      def register_interceptor(interceptor)
+        Mail.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.
+      def unregister_interceptor(interceptor)
+        Mail.unregister_interceptor(observer_class_for(interceptor))
+      end
+
+      def observer_class_for(value) # :nodoc:
+        case value
+        when String, Symbol
+          value.to_s.camelize.constantize
+        else
+          value
+        end
+      end
+      private :observer_class_for
+
+      # Define how the agent should generate content
+      def generate_with(provider, **options)
+        self.generation_provider = provider
+        self.options = (options || {}).merge(options)
+      end
+
+      def stream_with(&stream)
+        self.options = (options || {}).merge(stream: stream)
+      end
+
+      # Returns the name of the current agent. This method is also being used as a path for a view lookup.
+      # If this is an anonymous agent, this method will return +anonymous+ instead.
+      def agent_name
+        @agent_name ||= anonymous? ? "anonymous" : name.underscore
+      end
+      # Allows to set the name of current agent.
+      attr_writer :agent_name
+      alias_method :controller_path, :agent_name
+
+      # Sets the defaults through app configuration:
+      #
+      #     config.action_agent.default(from: "no-reply@example.org")
+      #
+      # Aliased by ::default_options=
+      def default(value = nil)
+        self.default_params = default_params.merge(value).freeze if value
+        default_params
+      end
+      # Allows to set defaults through app configuration:
+      #
+      #    config.action_agent.default_options = { from: "no-reply@example.org" }
+      alias_method :default_options=, :default
+
+      # Wraps a prompt generation inside of ActiveSupport::Notifications instrumentation.
+      #
+      # This method is actually called by the +ActionPrompt::Prompt+ object itself
+      # through a callback when you call <tt>:generate_prompt</tt> on the +ActionPrompt::Prompt+,
+      # calling +generate_prompt+ directly and passing an +ActionPrompt::Prompt+ will do
+      # nothing except tell the logger you generated the prompt.
+      def generate_prompt(prompt) # :nodoc:
+        ActiveSupport::Notifications.instrument("deliver.active_agent") do |payload|
+          set_payload_for_prompt(payload, prompt)
+          yield # Let Prompt do the generation actions
+        end
+      end
+
+      private
+
+      def set_payload_for_prompt(payload, prompt)
+        payload[:prompt] = prompt.encoded
+        payload[:agent] = name
+        payload[:message_id] = prompt.message_id
+        payload[:subject] = prompt.subject
+        payload[:to] = prompt.to
+        payload[:from] = prompt.from
+        payload[:bcc] = prompt.bcc if prompt.bcc.present?
+        payload[:cc] = prompt.cc if prompt.cc.present?
+        payload[:date] = prompt.date
+        payload[:perform_generations] = prompt.perform_generations
+      end
+
+      def method_missing(method_name, ...)
+        if action_methods.include?(method_name.name)
+          Generation.new(self, method_name, ...)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_all = false)
+        action_methods.include?(method.name) || super
+      end
+    end
+
+    attr_internal :context
+
+    def perform_generation
+      context.options.merge(options)
+      generation_provider.generate(context) if context && generation_provider
+    end
+
+    def initialize
+      super
+      @_prompt_was_called = false
+      @_context = ActiveAgent::ActionPrompt::Prompt.new(instructions: options[:instructions])
+    end
+
+    def process(method_name, *args) # :nodoc:
+      payload = {
+        agent: self.class.name,
+        action: method_name,
+        args: args
+      }
+
+      ActiveSupport::Notifications.instrument("process.active_agent", payload) do
+        super
+        @_context = ActiveAgent::ActionPrompt::Prompt.new unless @_prompt_was_called
+      end
+    end
+    ruby2_keywords(:process)
+
+    class NullPrompt # :nodoc:
+      def message
+        ""
+      end
+
+      def header
+        {}
+      end
+
+      def respond_to?(string, include_all = false)
+        true
+      end
+
+      def method_missing(...)
+        nil
+      end
+    end
+
+    # Returns the name of the agent object.
+    def agent_name
+      self.class.agent_name
+    end
+
+    def headers(args = nil)
+      if args
+        @_context.headers(args)
+      else
+        @_context
+      end
+    end
+
+    # def attachments
+    #   if @_prompt_was_called
+    #     LateAttachmentsProxy.new(@_context.attachments)
+    #   else
+    #     @_context.attachments
+    #   end
+    # end
+
+    class LateAttachmentsProxy < SimpleDelegator
+      def inline
+        self
+      end
+
+      def []=(_name, _content)
+        _raise_error
+      end
+
+      private
+
+      def _raise_error
+        raise "Can't add attachments after `prompt` was called.\n" \
+                              "Make sure to use `attachments[]=` before calling `prompt`."
+      end
+    end
+
+    def prompt(headers = {}, &block)
+      return context if @_prompt_was_called && headers.blank? && !block
+
+      content_type = headers[:content_type]
+
+      headers = apply_defaults(headers)
+
+      context.charset = charset = headers[:charset]
+
+      responses = collect_responses(headers, &block)
+      @_prompt_was_called = true
+
+      create_parts_from_responses(context, responses)
+
+      context.content_type = set_content_type(context, content_type, headers[:content_type])
+      context.charset = charset
+      context.actions = headers[:actions] || action_schemas
+      binding.irb
+      context
+    end
+    
+    def action_schemas
+      action_methods.map do |action|
+        JSON.parse render_to_string(locals: {action_name: action}, action: action, formats: :json)
+      end
+    end
+
+    private
+
+    def set_content_type(m, user_content_type, class_default) # :doc:
+      if user_content_type.present?
+        user_content_type
+      else
+        context.content_type || class_default
+      end
+    end
+
+    # Translates the +subject+ using \Rails I18n class under <tt>[agent_scope, action_name]</tt> scope.
+    # If it does not find a translation for the +subject+ under the specified scope it will default to a
+    # humanized version of the <tt>action_name</tt>.
+    # If the subject has interpolations, you can pass them through the +interpolations+ parameter.
+    def default_i18n_subject(interpolations = {}) # :doc:
+      agent_scope = self.class.agent_name.tr("/", ".")
+      I18n.t(:subject, **interpolations.merge(scope: [agent_scope, action_name], default: action_name.humanize))
+    end
+
+    def apply_defaults(headers)
+      default_values = self.class.default.except(*headers.keys).transform_values do |value|
+        compute_default(value)
+      end
+
+      headers.reverse_merge(default_values)
+    end
+
+    def compute_default(value)
+      return value unless value.is_a?(Proc)
+
+      if value.arity == 1
+        instance_exec(self, &value)
+      else
+        instance_exec(&value)
+      end
+    end
+
+    def assign_headers_to_context(context, headers)
+      assignable = headers.except(:parts_order, :content_type, :body, :template_name,
+        :template_path, :delivery_method, :delivery_method_options)
+      assignable.each { |k, v| context[k] = v }
+    end
+
+    def collect_responses(headers, &)
+      if block_given?
+        collect_responses_from_block(headers, &)
+      elsif headers[:body]
+        collect_responses_from_text(headers)
+      else
+        collect_responses_from_templates(headers)
+      end
+    end
+
+    def collect_responses_from_block(headers)
+      templates_name = headers[:template_name] || action_name
+      collector = ActiveAgent::ActionPrompt::Collector.new(lookup_context) { render(templates_name) }
+      yield(collector)
+      collector.responses
+    end
+
+    def collect_responses_from_text(headers)
+      [{
+        body: headers.delete(:body),
+        content_type: headers[:content_type] || "text/plain"
+      }]
+    end
+
+    def collect_responses_from_templates(headers)
+      templates_path = headers[:template_path] || self.class.agent_name
+      templates_name = headers[:template_name] || action_name
+
+      each_template(Array(templates_path), templates_name).map do |template|
+        format = template.format || formats.first
+        {
+          body: render(template: template, formats: [format]),
+          content_type: Mime[format].to_s
+        }
+      end
+    end
+
+    def each_template(paths, name, &)
+      templates = lookup_context.find_all(name, paths)
+      if templates.empty?
+        raise ActionView::MissingTemplate.new(paths, name, paths, false, "agent")
+      else
+        templates.uniq(&:format).each(&)
+      end
+    end
+
+    def create_parts_from_responses(context, responses)
+      if responses.size > 1 && false
+        prompt_container = ActiveAgent::ActionPrompt::Prompt.new
+        prompt_container.content_type = "multipart/alternative"
+        responses.each { |r| insert_part(context, r, context.charset) }
+        context.add_part(prompt_container)
+      else
+        responses.each { |r| insert_part(context, r, context.charset) }
+      end
+    end
+
+    def insert_part(container, response, charset)
+      response[:charset] ||= charset
+      container.add_part(response)
+    end
+
+    # This and #instrument_name is for caching instrument
+    def instrument_payload(key)
+      {
+        agent: agent_name,
+        key: key
+      }
+    end
+
+    def instrument_name
+      "active_agent"
+    end
+
+    def _protected_ivars
+      PROTECTED_IVARS
+    end
+
+    ActiveSupport.run_load_hooks(:active_agent, self)
+  end
+end

data/lib/active_agent/callbacks.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveSupport::Callbacks
+      define_callbacks :generate, skip_after_callbacks_if_terminated: true
+    end
+
+    module ClassMethods
+      # Defines a callback that will get called right before the
+      # prompt is sent to the generation provider method.
+      def before_generate(*filters, &)
+        set_callback(:generate, :before, *filters, &)
+      end
+
+      # Defines a callback that will get called right after the
+      # prompt's generation method is finished.
+      def after_generate(*filters, &)
+        set_callback(:generate, :after, *filters, &)
+      end
+
+      # Defines a callback that will get called around the prompt's generation method.
+      def around_generate(*filters, &)
+        set_callback(:generate, :around, *filters, &)
+      end
+    end
+  end
+end

data/lib/active_agent/deprecator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  def self.deprecator # :nodoc:
+    @deprecator ||= ActiveSupport::Deprecation.new
+  end
+end

data/lib/active_agent/engine.rb

@@ -0,0 +1,14 @@
+# require "rails/engine"
+
+# module ActiveAgent
+#   class Engine < ::Rails::Engine
+#     isolate_namespace ActiveAgent
+
+#     initializer "active_agent.view_paths" do |app|
+#       # Adding your gem's view path to Rails lookup paths
+#       ActiveSupport.on_load(:action_controller) do
+#         append_view_path Engine.root.join("app/views")
+#       end
+#     end
+#   end
+# end

data/lib/active_agent/generation.rb

@@ -0,0 +1,78 @@
+# lib/active_agent/generation.rb
+require "delegate"
+
+module ActiveAgent
+  class Generation < Delegator
+    def initialize(agent_class, action, *args)
+      @agent_class, @action, @args = agent_class, action, args
+      @processed_agent = nil
+      @prompt_context = nil
+    end
+    ruby2_keywords(:initialize)
+
+    def __getobj__
+      @prompt_context ||= processed_agent.context
+    end
+
+    def __setobj__(prompt_context)
+      @prompt_context = prompt_context
+    end
+
+    def context
+      __getobj__
+    end
+
+    def processed?
+      @processed_agent || @prompt_context
+    end
+
+    def generate_later!(options = {})
+      enqueue_generation :generate_now!, options
+    end
+
+    def generate_later(options = {})
+      enqueue_generation :generate_now, options
+    end
+
+    def generate_now!
+      processed_agent.handle_exceptions do
+        processed_agent.run_callbacks(:generate) do
+          processed_agent..perform_generation
+        end
+      end
+    end
+
+    def generate_now
+      processed_agent.handle_exceptions do
+        processed_agent.run_callbacks(:generate) do
+          processed_agent.perform_generation
+        end
+      end
+    end
+
+    private
+
+    def processed_agent
+      @processed_agent ||= @agent_class.new.tap do |agent|
+        agent.process(@action, *@args)
+      end
+    end
+
+    def enqueue_generation(generation_method, options = {})
+      if processed?
+        ::Kernel.raise "You've accessed the context before asking to " \
+          "generate it later, so you may have made local changes that would " \
+          "be silently lost if we enqueued a job to generate it. Why? Only " \
+          "the agent method *arguments* are passed with the generation job! " \
+          "Do not access the context in any way if you mean to generate it " \
+          "later. Workarounds: 1. don't touch the context before calling " \
+          "#generate_later, 2. only touch the context *within your agent " \
+          "method*, or 3. use a custom Active Job instead of #generate_later."
+      else
+        @agent_class.generation_job.set(options).perform_later(
+          @agent_class.name, @action.to_s, args: @args
+        )
+      end
+    end
+  end
+end

data/lib/active_agent/generation_job.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module ActiveAgent
+  # = Active Agent \GenerationJob
+  #
+  # The +ActiveAgent::GenerationJob+ class is used when you
+  # want to generate content outside of the request-response cycle. It supports
+  # sending messages with parameters.
+  #
+  # Exceptions are rescued and handled by the agent class.
+  class GenerationJob < ActiveJob::Base # :nodoc:
+    queue_as do
+      agent_class = arguments.first.constantize
+      agent_class.generate_later_queue_name
+    end
+
+    rescue_from StandardError, with: :handle_exception_with_agent_class
+
+    def perform(agent_class_name, action_name, args:, params: nil)
+      agent_class = agent_class_name.constantize
+      agent = agent_class.new
+      agent.params = params if params
+      agent.process(action_name, *args)
+      agent.generate
+    end
+
+    private
+
+    # "Deserialize" the agent class name by hand in case another argument
+    # (like a Global ID reference) raised DeserializationError.
+    def agent_class
+      if agent = Array(@serialized_arguments).first || Array(arguments).first
+        agent.constantize
+      end
+    end
+
+    def handle_exception_with_agent_class(exception)
+      if klass = agent_class
+        klass.handle_exception exception
+      else
+        raise exception
+      end
+    end
+  end
+end

data/lib/active_agent/generation_methods.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "action_prompt"
+
+module ActiveAgent
+  # = Active Agent \GenerationM74ethods
+  #
+  # This module handles everything related to prompt generation, from registering
+  # new generation methods to configuring the prompt object to be sent.
+  module GenerationMethods
+    extend ActiveSupport::Concern
+
+    included do
+      # Do not make this inheritable, because we always want it to propagate
+      cattr_accessor :raise_generation_errors, default: true
+      cattr_accessor :perform_generations, default: true
+
+      class_attribute :generation_methods, default: {}.freeze
+      class_attribute :generation_method, default: :smtp
+
+      add_generation_method :test, ActiveAgent::ActionPrompt::TestAgent
+    end
+
+    module ClassMethods
+      delegate :generations, :generations=, to: ActiveAgent::ActionPrompt::TestAgent
+
+      def add_generation_method(symbol, klass, default_options = {})
+        class_attribute(:"#{symbol}_settings") unless respond_to?(:"#{symbol}_settings")
+        public_send(:"#{symbol}_settings=", default_options)
+        self.generation_methods = generation_methods.merge(symbol.to_sym => klass).freeze
+      end
+
+      def wrap_generation_behavior(prompt, method = nil, options = nil) # :nodoc:
+        method ||= generation_method
+        prompt.generation_handler = self
+
+        case method
+        when NilClass
+          raise "Generation method cannot be nil"
+        when Symbol
+          if klass = generation_methods[method]
+            prompt.generation_method(klass, (send(:"#{method}_settings") || {}).merge(options || {}))
+          else
+            raise "Invalid generation method #{method.inspect}"
+          end
+        else
+          prompt.generation_method(method)
+        end
+
+        prompt.perform_generations = perform_generations
+        prompt.raise_generation_errors = raise_generation_errors
+      end
+    end
+
+    def wrap_generation_behavior!(*) # :nodoc:
+      self.class.wrap_generation_behavior(prompt, *)
+    end
+  end
+end

data/lib/active_agent/generation_provider/README.md

@@ -0,0 +1,17 @@
+# Active Agent: Generation Provider
+
+This README provides information about the base generation provider class and the generation provider module interfaces in the ActiveAgent library.
+
+## Main Components
+
+Base class - for creating and configuring generation providers.
+Module - for including in your agent classes to provide generation provider functionality.
+
+### ActiveAgent::GenerationProvider::Base
+
+The main class for creating and configuring generation providers. It provides the core functionality for creating and managing generation providers.
+
+#### Core Methods
+
+##### initialize(options = {})
+Creates a new generation provider object with the given options.