action_ai 0.1.0

data/lib/action_ai/execution_job.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module ActionAI
+  # = Action AI \ExecutionJob
+  #
+  # The +ActionAI::ExecutionJob+ class is used when you
+  # want to execute AI-powered jobs outside of the request-response cycle. It supports
+  # executing either parameterized or normal actions.
+  #
+  # Exceptions are rescued and handled by the agent class.
+  class ExecutionJob < ActiveJob::Base # :nodoc:
+    queue_as do
+      arguments.first.constantize
+        .execute_later_queue_name
+    end
+
+    rescue_from StandardError, with: :handle_exception_with_agent_class
+
+    def perform(agent, action, args: [], kwargs: {}, params: nil)
+      agent.constantize
+        .then { params ? it.with(params) : it }
+        .public_send(action, *args, **kwargs)
+        .run
+    end
+
+    private
+      # "Deserialize" the agent class name by hand in case another argument
+      # (like a Global ID reference) raised DeserializationError.
+      def agent_class
+        [@serialized_arguments, arguments]
+          .filter_map { Array(it).first }
+          .first&.constantize
+      end
+
+      def handle_exception_with_agent_class(exception)
+        agent_class&.handle_exception exception or
+          raise exception
+      end
+  end
+end

data/lib/action_ai/interaction.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ActionAI
+  # = Action AI \Interaction
+  #
+  # The +ActionAI::Interaction+ class is used by
+  # ActionAI::Agent when creating a new agent.
+  # <tt>Interaction</tt> is a wrapper (+Delegator+ subclass) around a lazy
+  # created +RubyLLM::Message+. You can get direct access to the
+  # +RubyLLM::Message+ or schedule the job to be executed
+  # through Active Job.
+  #
+  #   Generator.code(task)         # an ActionAI::Interaction object
+  #   Generator.code(task).content # executes and returns the result
+  #   Generator.code(task).later   # enqueue execution as a job through Active Job
+  #   Generator.code(task).message # a RubyLLM::Message object
+  class Interaction < Delegator
+    def initialize(agent_class, action, *args) # :nodoc:
+      @agent_class, @action, @args = agent_class, action, args
+
+      # The AI interaction is only processed if we try to call any methods on it.
+      # Typical usage will leave it unloaded and call +later+.
+      @processed_agent = nil
+      @message = nil
+    end
+    ruby2_keywords(:initialize)
+
+    # Method calls are delegated to the RubyLLM::Message that's ready to execute.
+    def __getobj__ # :nodoc:
+      @message ||= processed_agent.handle_exceptions do
+        processed_agent.run_callbacks(:execution) do
+          processed_agent.message
+        end
+      end.presence
+    end
+
+    # Unused except for delegator internals (dup, marshalling).
+    def __setobj__(message) # :nodoc:
+      @message = message
+    end
+
+    # Returns the resulting RubyLLM::Message
+    def message
+      __getobj__
+    end
+
+    # Was the delegate loaded, causing the action to be processed?
+    def processed?
+      @processed_agent || @message
+    end
+
+    def run = message
+
+    # Enqueues the action to be executed through Active Job.
+    #
+    #   Generator.code(task).later
+    #   Generator.code(task).later(wait: 1.hour)
+    #   Generator.code(task).later(wait_until: 10.hours.from_now)
+    #   Generator.code(task).later(priority: 10)
+    #
+    # Options:
+    #
+    # * <tt>:wait</tt> - Enqueue the action to be executed with a delay.
+    # * <tt>:wait_until</tt> - Enqueue the action to be executed at (after) a specific date / time.
+    # * <tt>:queue</tt> - Enqueue the action on the specified queue.
+    # * <tt>:priority</tt> - Enqueues the action with the specified priority
+    #
+    # By default, the action will be enqueued using ActionAI::ExecutionJob on
+    # the default queue. Agent classes can customize the queue name used for the default
+    # job by assigning a +execute_later_queue_name+ class variable, or provide a custom job
+    # by assigning a +execution_job+. When a custom job is used, it controls the queue name.
+    #
+    #   class CostlyAgent < ApplicationAI
+    #     self.execution_job = CostlyExecutionJob
+    #   end
+    def later(...) = enqueue_execution(...)
+
+    private
+      # Returns the processed Agent instance. We keep this instance
+      # on hand so we can run callbacks and delegate exception handling to it.
+      def processed_agent
+        @processed_agent ||= @agent_class.new.tap do
+          it.process @action, *@args
+        end
+      end
+
+      def enqueue_execution(...)
+        if processed?
+          ::Kernel.raise "You've used the AI agent before asking to " \
+            "call it later, so you may have made local changes that would " \
+            "be silently lost if we enqueued a job to execute it. Why? Only " \
+            "the agent method *arguments* are passed with the execution job! " \
+            "Do not use the AI agent in any way if you mean to call it " \
+            "later. Workarounds: 1. don't touch the agent before calling " \
+            "#later, 2. only touch the agent *within your agent " \
+            "method*, or 3. use a custom Active Job instead of #later."
+        else
+          @agent_class.execution_job.set(...).perform_later(
+            @agent_class.name, @action.to_s, args: @args)
+        end
+      end
+  end
+end

data/lib/action_ai/log_subscriber.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "active_support/log_subscriber"
+
+module ActionAI
+  # = Action AI \LogSubscriber
+  #
+  # Implements the ActiveSupport::LogSubscriber for logging notifications when
+  # a prompt is executed.
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    # A prompt was processed.
+    def process(event)
+      debug do
+        agent  = event.payload[:agent]
+        action = event.payload[:action]
+        "#{agent}##{action}: executed prompt in #{event.duration.round(1)}ms"
+      end
+    end
+    subscribe_log_level :process, :debug
+
+    # Use the logger configured for ActionAI::Agent.
+    def logger
+      ActionAI::Agent.logger
+    end
+  end
+end
+
+ActionAI::LogSubscriber.attach_to :action_ai

data/lib/action_ai/parameterized.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ActionAI
+  # = Action AI \Parameterized
+  #
+  # Provides the option to parameterize AI agents in order to share instance variable
+  # setup, processing, and common defaults.
+  #
+  # Consider this example that does not use parameterization:
+  #
+  #   class InvitationAgent < ApplicationAI
+  #     def account_invitation(inviter, invitee)
+  #       @account = inviter.account
+  #       @inviter = inviter
+  #       @invitee = invitee
+  #     end
+  #
+  #     def project_invitation(project, inviter, invitee)
+  #       @account = inviter.account
+  #       @project = project
+  #       @inviter = inviter
+  #       @invitee = invitee
+  #       @summarizer = ProjectInvitationSummarizer.new(@project.bucket)
+  #     end
+  #
+  #     def bulk_project_invitation(projects, inviter, invitee)
+  #       @account  = inviter.account
+  #       @projects = projects.sort_by(&:name)
+  #       @inviter  = inviter
+  #       @invitee  = invitee
+  #     end
+  #   end
+  #
+  #   InvitationAgent.account_invitation(person_a, person_b).later
+  #
+  # Using parameterized agents, this can be rewritten as:
+  #
+  #   class InvitationAgent < ApplicationAI
+  #     before_action { @inviter, @invitee = params[:inviter], params[:invitee] }
+  #     before_action { @account = params[:inviter].account }
+  #
+  #     def account_invitation
+  #     end
+  #
+  #     def project_invitation
+  #       @project = params[:project]
+  #       @summarizer = ProjectInvitationSummarizer.new(@project.bucket)
+  #     end
+  #
+  #     def bulk_project_invitation
+  #       @projects = params[:projects].sort_by(&:name)
+  #     end
+  #   end
+  #
+  #   InvitationAgent.with(inviter: person_a, invitee: person_b).account_invitation.later
+  module Parameterized
+    extend ActiveSupport::Concern
+
+    included do
+      attr_writer :params
+
+      def params
+        @params ||= {}
+      end
+    end
+
+    module ClassMethods
+      # Provide the parameters to the agent in order to use them in the instance methods and callbacks.
+      #
+      #   InvitationAgent.with(inviter: person_a, invitee: person_b).account_invitation.later
+      #
+      # See Parameterized documentation for full example.
+      def with(params)
+        ActionAI::Parameterized::Agent.new(self, params)
+      end
+    end
+
+    class Agent # :nodoc:
+      def initialize(agent, params)
+        @agent, @params = agent, params
+      end
+
+      private
+        def method_missing(method_name, ...)
+          if @agent.action_methods.include?(method_name.name)
+            ActionAI::Parameterized::PromptExecution.new(@agent, method_name, @params, ...)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(method, include_all = false)
+          @agent.respond_to?(method, include_all)
+        end
+    end
+
+    class PromptExecution < ActionAI::Interaction # :nodoc:
+      def initialize(agent_class, action, params, ...)
+        super(agent_class, action, ...)
+        @params = params
+      end
+
+      private
+        def processed_agent
+          @processed_agent ||= @agent_class.new.tap do |agent|
+            agent.params = @params
+            agent.process @action, *@args
+          end
+        end
+
+        def enqueue_execution(...)
+          if processed?
+            super
+          else
+            @agent_class.execution_job.set(...).perform_later(
+              @agent_class.name, @action.to_s, params: @params, args: @args)
+          end
+        end
+    end
+  end
+end

data/lib/action_ai/preview.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "active_support/descendants_tracker"
+
+module ActionAI
+  module Previews # :nodoc:
+    extend ActiveSupport::Concern
+
+    included do
+      # Add the location of AI agent previews through app configuration:
+      #
+      #     config.action_ai.preview_paths << "#{Rails.root}/lib/ai/previews"
+      #
+      mattr_accessor :preview_paths, instance_writer: false, default: []
+
+      # Enable or disable prompt previews through app configuration:
+      #
+      #     config.action_ai.show_previews = true
+      #
+      # Defaults to +true+ for development environment
+      #
+      mattr_accessor :show_previews, instance_writer: false
+    end
+  end
+
+  class Preview
+    extend ActiveSupport::DescendantsTracker
+
+    attr_reader :params
+
+    def initialize(params = {})
+      @params = params
+    end
+
+    class << self
+      # Returns all agent preview classes.
+      def all
+        load_previews if descendants.empty?
+        descendants.sort_by { it.name.titleize }
+      end
+
+      # Returns the message object for the given action name.
+      def call(action, params = {})
+        preview = new(params)
+        message = preview.public_send(action)
+        message
+      end
+
+      # Returns all of the available action previews.
+      def actions
+        public_instance_methods(false).map(&:to_s).sort
+      end
+
+      # Returns +true+ if the action exists.
+      def action_exists?(action)
+        actions.include?(action)
+      end
+
+      # Returns +true+ if the preview exists.
+      def exists?(preview)
+        all.any? { |p| p.preview_name == preview }
+      end
+
+      # Find an agent preview by its underscored class name.
+      def find(preview)
+        all.find { |p| p.preview_name == preview }
+      end
+
+      # Returns the underscored name of the agent preview without the suffix.
+      def preview_name
+        name.delete_suffix("Preview").underscore
+      end
+
+      private
+        def load_previews
+          preview_paths.each do |preview_path|
+            Dir["#{preview_path}/**/*_preview.rb"].sort.each { |file| require file }
+          end
+        end
+
+        def preview_paths
+          Agent.preview_paths
+        end
+
+        def show_previews
+          Agent.show_previews
+        end
+    end
+  end
+end

data/lib/action_ai/prompt_helper.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ActionAI
+  # = Action AI \PromptHelper
+  #
+  # Provides helper methods for ActionAI::Agent that can be used for easily
+  # formatting messages, accessing agent or message instances, and the
+  # attachments list.
+  module PromptHelper
+    # Take the text and format it, indented two spaces for each line, and
+    # wrapped at 72 columns:
+    #
+    #   text = <<-TEXT
+    #     This is
+    #     the      paragraph.
+    #
+    #     * item1 * item2
+    #   TEXT
+    #
+    #   block_format text
+    #   # => "  This is the paragraph.\n\n  * item1\n  * item2\n"
+    def block_format(text)
+      formatted = text.split(/\n\r?\n/).collect { |paragraph|
+        format_paragraph(paragraph)
+      }.join("\n\n")
+
+      # Make list points stand on their own line
+      output = +""
+      splits = formatted.split(/(\*+|\#+)/)
+      while line = splits.shift
+        if line.start_with?("*", "#") && splits.first&.start_with?(" ")
+          output.chomp!(" ") while output.end_with?(" ")
+          output << "  #{line} #{splits.shift.strip}\n"
+        else
+          output << line
+        end
+      end
+
+      output
+    end
+
+    # Access the agent instance.
+    def agent
+      @_controller
+    end
+
+    # Access the message instance.
+    def message
+      @_message
+    end
+
+    # Access the message attachments list.
+    def attachments
+      agent.attachments
+    end
+
+    # Returns +text+ wrapped at +len+ columns and indented +indent+ spaces.
+    # By default column length +len+ equals 72 characters and indent
+    # +indent+ equal two spaces.
+    #
+    #   my_text = 'Here is a sample text with more than 40 characters'
+    #
+    #   format_paragraph(my_text, 25, 4)
+    #   # => "    Here is a sample text with\n    more than 40 characters"
+    def format_paragraph(text, len = 72, indent = 2)
+      sentences = [[]]
+
+      text.split.each do |word|
+        if sentences.first.present? && (sentences.last + [word]).join(" ").length > len
+          sentences << [word]
+        else
+          sentences.last << word
+        end
+      end
+
+      indentation = " " * indent
+      sentences.map! { |sentence|
+        "#{indentation}#{sentence.join(' ')}"
+      }.join "\n"
+    end
+  end
+end

data/lib/action_ai/queued_execution.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActionAI
+  module QueuedExecution
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :execution_job, default: ::ActionAI::ExecutionJob
+      class_attribute :execute_later_queue_name, default: :ai_agents
+    end
+  end
+end

data/lib/action_ai/railtie.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "active_job/railtie"
+require "action_ai"
+require "rails"
+require "abstract_controller/railties/routes_helpers"
+
+module ActionAI
+  class Railtie < Rails::Railtie # :nodoc:
+    config.action_ai = ActiveSupport::OrderedOptions.new
+    config.action_ai.preview_paths = []
+    config.eager_load_namespaces << ActionAI
+
+    initializer "action_ai.deprecator", before: :load_environment_config do |app|
+      app.deprecators[:action_ai] = ActionAI.deprecator
+    end
+
+    initializer "action_ai.logger" do
+      ActiveSupport.on_load(:action_ai) { self.logger ||= Rails.logger }
+    end
+
+    initializer "action_ai.set_configs" do |app|
+      paths   = app.config.paths
+      options = app.config.action_ai
+
+      options.assets_dir      ||= paths["public"].first
+      options.javascripts_dir ||= paths["public/javascripts"].first
+      options.stylesheets_dir ||= paths["public/stylesheets"].first
+      options.show_previews = Rails.env.development? if options.show_previews.nil?
+      options.cache_store ||= Rails.cache
+      options.preview_paths |= ["#{Rails.root}/test/ai/previews"]
+
+      # make sure readers methods get compiled
+      options.asset_host          ||= app.config.asset_host
+      options.relative_url_root   ||= app.config.relative_url_root
+
+      ActiveSupport.on_load(:action_ai) do
+        include AbstractController::UrlFor
+        extend ::AbstractController::Railties::RoutesHelpers.with(app.routes, false)
+        include app.routes.mounted_helpers
+
+        self.preview_paths |= options[:preview_paths]
+        self.view_paths = ["#{Rails.root}/app/ai/prompts"]
+
+        if execution_job = options.delete(:execution_job)
+          self.execution_job = execution_job.constantize
+        end
+
+        options.each { |k, v| send("#{k}=", v) }
+      end
+
+      ActiveSupport.on_load(:action_dispatch_integration_test) do
+        include ActionAI::TestHelper
+      end
+    end
+
+    initializer "action_ai.set_autoload_paths", before: :set_autoload_paths do |app|
+      options = app.config.action_ai
+      app.config.paths["test/ai/prompts/previews"].concat(options.preview_paths)
+    end
+
+    config.after_initialize do |app|
+      options = app.config.action_ai
+
+      if options.show_previews
+        app.routes.prepend do
+          get "/rails/ai/agents"                => "rails/ai/agents#index",    internal: true
+          get "/rails/ai/agents/download/*path" => "rails/ai/agents#download", internal: true
+          get "/rails/ai/agents/*path"          => "rails/ai/agents#preview",  internal: true
+        end
+      end
+    end
+  end
+end

data/lib/action_ai/rescuable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActionAI # :nodoc:
+  # = Action AI \Rescuable
+  #
+  # Provides
+  # {rescue_from}[rdoc-ref:ActiveSupport::Rescuable::ClassMethods#rescue_from]
+  # for AI agents. Wraps agent action processing and job execution to handle
+  # configured errors.
+  module Rescuable
+    extend ActiveSupport::Concern
+    include ActiveSupport::Rescuable
+
+    class_methods do
+      def handle_exception(exception) # :nodoc:
+        rescue_with_handler(exception) || raise(exception)
+      end
+    end
+
+    def handle_exceptions # :nodoc:
+      yield
+    rescue => exception
+      rescue_with_handler(exception) || raise
+    end
+
+    private
+      def process(...)
+        handle_exceptions do
+          super
+        end
+      end
+  end
+end

data/lib/action_ai/test_case.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "active_support/test_case"
+require "rails-dom-testing"
+
+module ActionAI
+  class NonInferrableAgentError < ::StandardError
+    def initialize(name)
+      super "Unable to determine the agent to test from #{name}. " \
+        "You'll need to specify it using tests YourAgent in your " \
+        "test case definition"
+    end
+  end
+
+  class TestCase < ActiveSupport::TestCase
+    module ClearTestInteractions
+      extend ActiveSupport::Concern
+
+      included do
+        setup :clear_test_interactions
+        teardown :clear_test_interactions
+      end
+
+      private
+        def clear_test_interactions
+          if ActionAI.respond_to? :interactions
+            ActionAI.interactions.clear
+          end
+        end
+    end
+
+    module Behavior
+      extend ActiveSupport::Concern
+
+      include ActiveSupport::Testing::ConstantLookup
+      include TestHelper
+      include Rails::Dom::Testing::Assertions::SelectorAssertions
+      include Rails::Dom::Testing::Assertions::DomAssertions
+
+      included do
+        class_attribute :_agent_class
+        setup :initialize_test_interactions
+        setup :set_expected_message
+        ActiveSupport.run_load_hooks(:action_ai_test_case, self)
+      end
+
+      module ClassMethods
+        def tests(agent)
+          case agent
+          when String, Symbol
+            self._agent_class = agent.to_s.camelize.constantize
+          when Module
+            self._agent_class = agent
+          else
+            raise NonInferrableAgentError.new(agent)
+          end
+        end
+
+        def agent_class
+          _agent_class or
+            tests determine_default_agent(name)
+        end
+
+        def determine_default_agent(name)
+          determine_constant_from_test_name(name) do |constant|
+            Class === constant && constant < ActionAI::Agent
+          end or
+            raise NonInferrableAgentError.new(name)
+        end
+      end
+
+      # Reads the fixture file for the given agent.
+      #
+      # This is useful when testing agents by being able to write the body of
+      # a prompt inside a fixture. See the testing guide for a concrete example:
+      # https://guides.rubyonrails.org/testing.html#revenge-of-the-fixtures
+      def read_fixture(action)
+        IO.readlines(File.join(Rails.root, "test", "fixtures", self.class.agent_class.name.underscore, action))
+      end
+
+      private
+        def initialize_test_interactions
+          ActionAI.interactions.clear
+        end
+
+        def set_expected_message
+          @expected = RubyLLM::Message.new(
+            role: :system,
+            content: "",
+          )
+        end
+    end
+
+    include Behavior
+  end
+end