action_ai 0.1.0

data/lib/action_ai/test_helper.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/array/extract_options"
+require "active_job"
+require "ruby_llm/tester"
+
+RubyLLM.configure do
+  it.default_model = "echo"
+end
+
+module ActionAI
+  # Provides a list of prompts that have been executed by RubyLLM::Tester
+  singleton_class.delegate :interactions, to: RubyLLM::Tester
+
+  # Provides helper methods for testing Action AI, including #assert_ai_prompts
+  # and #assert_no_ai_prompts.
+  module TestHelper
+    include ActiveJob::TestHelper
+
+    # Asserts that the number of AI prompts executed matches the given number.
+    #
+    #   def test_prompts
+    #     assert_ai_prompts 0
+    #     Generator.code(task).run
+    #     assert_ai_prompts 1
+    #     Generator.code(task).run
+    #     assert_ai_prompts 2
+    #   end
+    #
+    # If a block is passed, that block should cause the specified number of
+    # prompts to be executed.
+    #
+    #   def test_ai_prompts_again
+    #     assert_ai_prompts 1 do
+    #       Generator.code(task).run
+    #     end
+    #
+    #     assert_ai_prompts 2 do
+    #       Generator.code(task).run
+    #       Generator.code(task).later
+    #     end
+    #   end
+    def assert_ai_prompts(number, &block)
+      if block_given?
+        diff = capture_ai_prompts(&block).length
+        assert_equal number, diff, "#{number} prompts expected, but #{diff} were executed"
+      else
+        assert_equal number, ActionAI.interactions.size
+      end
+    end
+
+    # Asserts that no AI prompts have been executed.
+    #
+    #   def test_prompts
+    #     assert_no_ai_prompts
+    #     Generator.code(task).run
+    #     assert_ai_prompts 1
+    #   end
+    #
+    # If a block is passed, that block should not cause any prompts to be executed.
+    #
+    #   def test_prompts_again
+    #     assert_no_ai_prompts do
+    #       # No prompts should be executed from this block
+    #     end
+    #   end
+    #
+    # Note: This assertion is simply a shortcut for:
+    #
+    #   assert_ai_prompts 0, &block
+    def assert_no_ai_prompts(&block)
+      assert_ai_prompts 0, &block
+    end
+
+    # Asserts that the number of AI jobs enqueued for later processing matches
+    # the given number.
+    #
+    #   def test_jobs
+    #     assert_enqueued_ai_jobs 0
+    #     Generator.code(task).later
+    #     assert_enqueued_ai_jobs 1
+    #     Generator.code(task).later
+    #     assert_enqueued_ai_jobs 2
+    #   end
+    #
+    # If a block is passed, that block should cause the specified number of
+    # jobs to be enqueued.
+    #
+    #   def test_jobs_again
+    #     assert_enqueued_ai_jobs 1 do
+    #       Generator.code(task).later
+    #     end
+    #
+    #     assert_enqueued_ai_jobs 2 do
+    #       Generator.code(task).later
+    #       Generator.code(task).later
+    #     end
+    #   end
+    def assert_enqueued_ai_jobs(number, &block)
+      assert_enqueued_jobs(number, only: ->(job) { ai_job_filter(job) }, &block)
+    end
+
+    # Asserts that a specific AI job has been enqueued, optionally
+    # matching arguments and/or params.
+    #
+    #   def test_job
+    #     Generator.code.later
+    #     assert_enqueued_ai_job_with Generator, :code
+    #   end
+    #
+    #   def test_job_with_parameters
+    #     Generator.with(context: "MVP").later
+    #     assert_enqueued_ai_job_with Generator, :code, params: { context: "MVP" }
+    #   end
+    #
+    #   def test_job_with_arguments
+    #     Generator.code(task).later
+    #     assert_enqueued_ai_job_with Generator, :code, args: [task]
+    #   end
+    #
+    #   def test_job_with_named_arguments
+    #     Generator.code(task:).later
+    #     assert_enqueued_ai_job_with Generator, :code, args: [{task:}]
+    #   end
+    #
+    #   def test_job_with_parameters_and_arguments
+    #     Generator.with(context: "MVP").code(task).later
+    #     assert_enqueued_ai_job_with Generator, :code, params: { context: "MVP" }, args: [task]
+    #   end
+    #
+    #   def test_job_with_parameters_and_named_arguments
+    #     Generator.with(context: "MVP").code(task:).later
+    #     assert_enqueued_ai_job_with Generator, :code, params: { context: "MVP" }, args: [{task:}]
+    #   end
+    #
+    #   def test_job_with_parameterized_agent
+    #     Generator.with(context: "MVP").code.later
+    #     assert_enqueued_ai_job_with Generator.with(context: "MVP"), :code
+    #   end
+    #
+    #   def test_job_with_matchers
+    #     Generator.with(context: "MVP").code(task).later
+    #     assert_enqueued_ai_job_with Generator, :code,
+    #       params: ->(params) { /mvp/i.match?(params[:context]) },
+    #       args: ->(args) { task == args[0] }
+    #   end
+    #
+    # If a block is passed, that block should cause the specified job
+    # to be enqueued.
+    #
+    #   def test_job_in_block
+    #     assert_enqueued_ai_job_with Generator, :code do
+    #       Generator.code(task).later
+    #     end
+    #   end
+    #
+    # If +args+ is provided as a Hash, a parameterized job is matched.
+    #
+    #   def test_parameterized_job
+    #     assert_enqueued_ai_job_with Generator, :code,
+    #       args: {context: "MVP"} do
+    #       Generator.with(context: "MVP").code.later
+    #     end
+    #   end
+    def assert_enqueued_ai_job_with(agent, method, params: nil, args: nil, queue: nil, &block)
+      if agent.is_a? ActionAI::Parameterized::Agent
+        params = agent.instance_variable_get(:@params)
+        agent = agent.instance_variable_get(:@agent)
+      end
+
+      args = Array(args) unless args.is_a?(Proc)
+      queue ||= agent.execute_later_queue_name || ActiveJob::Base.default_queue_name
+
+      expected = ->(job_args) do
+        job_kwargs = job_args.extract_options!
+
+        [agent.to_s, method.to_s] == job_args &&
+          params === job_kwargs[:params] && args === job_kwargs[:args]
+      end
+
+      assert_enqueued_with(job: agent.execution_job, args: expected, queue: queue.to_s, &block)
+    end
+
+    # Asserts that no AI jobs are enqueued for later processing.
+    #
+    #   def test_no_jobs
+    #     assert_no_enqueued_ai_jobs
+    #     Generator.code(task).later
+    #     assert_enqueued_ai_jobs 1
+    #   end
+    #
+    # If a block is provided, it should not cause any AI jobs to be enqueued.
+    #
+    #   def test_no_jobs
+    #     assert_no_enqueued_ai_jobs do
+    #       # No AI jobs should be enqueued from this block
+    #     end
+    #   end
+    def assert_no_enqueued_ai_jobs(&block)
+      assert_enqueued_ai_jobs 0, &block
+    end
+
+    # Executes all enqueued AI jobs. If a block is given, executes all of the jobs
+    # that were enqueued throughout the duration of the block. If a block is
+    # not given, executes all the enqueued jobs up to this point in the test.
+    #
+    #   def test_execute_enqueued_jobs
+    #     perform_enqueued_ai_jobs do
+    #       Generator.code(task).later
+    #     end
+    #
+    #     assert_ai_prompts 1
+    #   end
+    #
+    #   def test_execute_enqueued_jobs_without_block
+    #     Generator.code(task).later
+    #
+    #     perform_enqueued_ai_jobs
+    #
+    #     assert_ai_prompts 1
+    #   end
+    #
+    # If the +:queue+ option is specified,
+    # then only the prompts enqueued to a specific queue will be performed.
+    #
+    #   def test_execute_enqueued_jobs_with_queue
+    #     perform_enqueued_ai_jobs queue: :external_agents do
+    #       Generator.execution_later_queue_name = :external_agents
+    #       Generator.code(task).later # will be performed
+    #       Notifier.execution_later_queue_name = :internal_agents
+    #       Notifier.welcome.later # will not be performed
+    #     end
+    #
+    #     assert_ai_prompts 1
+    #   end
+    #
+    # If the +:at+ option is specified, then only executes prompts enqueued to execution
+    # immediately or before the given time.
+    def perform_enqueued_ai_jobs(queue: nil, at: nil, &block)
+      perform_enqueued_jobs(only: ->(job) { ai_job_filter(job) }, queue: queue, at: at, &block)
+    end
+
+    # Returns any AI prompts that are executed in the block.
+    #
+    #   def test_ai_prompts
+    #     prompts = capture_ai_prompts do
+    #       Generator.code(task).content
+    #     end
+    #     assert_match /Write .*code/, prompts.first.content
+    #
+    #     prompts = capture_ai_prompts do
+    #       Generator.code(task).content
+    #       Generator.code(task).later
+    #     end
+    #     assert_match /Write .*code/, prompts.first.content
+    #   end
+    def capture_ai_prompts(&block)
+      original_count = ActionAI.interactions.size
+      perform_enqueued_ai_jobs(&block)
+      new_count = ActionAI.interactions.size
+      diff = new_count - original_count
+      ActionAI.interactions.last(diff)
+    end
+
+    private
+      def ai_job_filter(job)
+        job_class = job.is_a?(Hash) ? job.fetch(:job) : job.class
+
+        Agent.descendants.map(&:execution_job).include?(job_class)
+      end
+  end
+end

data/lib/action_ai/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActionAI
+  VERSION = "0.1.0"
+end

data/lib/action_ai.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+#--
+# Copyright (c) David Heinemeier Hansson
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+require "abstract_controller"
+require "action_ai/version"
+require "action_ai/deprecator"
+
+# Common Active Support usage in Action AI
+require "active_support"
+require "active_support/rails"
+require "active_support/core_ext/class"
+require "active_support/core_ext/module/attr_internal"
+require "active_support/core_ext/string/inflections"
+require "active_support/lazy_load_hooks"
+
+# :include: ../README.rdoc
+module ActionAI
+  extend ::ActiveSupport::Autoload
+
+  autoload :Agent
+  autoload :Callbacks
+  autoload :PromptHelper
+  autoload :Parameterized
+  autoload :Preview
+  autoload :Previews, "action_ai/preview"
+  autoload :TestCase
+  autoload :TestHelper
+  autoload :Interaction
+  autoload :ExecutionJob
+  autoload :QueuedExecution
+
+  def self.eager_load!
+    super
+
+    require "ruby_llm"
+    RubyLLM.eager_autoload!
+
+    Agent.descendants
+         .reject(&:abstract?)
+         .each(&:eager_load!)
+  end
+end
+
+autoload :Mime, "action_dispatch/http/mime_type"
+
+ActiveSupport.on_load(:action_view) do
+  ActionView::Base.default_formats ||= Mime::SET.symbols
+  ActionView::Template.mime_types_implementation = Mime
+  ActionView::LookupContext::DetailsKey.clear
+end

data/lib/rails/generators/ai/USAGE

@@ -0,0 +1,20 @@
+Description:
+    Generates a new AI agent and its prompts. Passes the agent name, either
+    CamelCased or under_scored, and an optional list of prompts as arguments.
+
+    This generates an agent class in app/ai/agents and invokes your template
+    engine and test framework generators.
+
+Examples:
+    `bin/rails generate ai generator`
+
+    creates a generator agent class, prompts, and test:
+        Agent:      app/ai/agents/generator.rb
+        Views:      app/ai/prompts/generator/code.erb [...]
+        Test:       test/ai/agents/generator_test.rb
+
+    `bin/rails generate ai generator text image video`
+
+    creates a generator agent with text, image, and video actions.
+
+

data/lib/rails/generators/ai/ai_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Rails
+  module Generators
+    class AIGenerator < NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :actions, type: :array, default: [], banner: "method method"
+
+      def create_agent_file
+        template "agent.rb", File.join("app/ai/agents", class_path, "#{file_name}.rb")
+
+        in_root do
+          if behavior == :invoke && !File.exist?(application_agent_file_name)
+            template "application_agent.rb", application_agent_file_name
+          end
+        end
+      end
+
+      hook_for :template_engine, :test_framework
+
+      private
+        def application_agent_file_name
+          @_application_agent_file_name ||= if mountable_engine?
+            "app/ai/agents/#{namespaced_path}/application_ai.rb"
+          else
+            "app/ai/agents/application_ai.rb"
+          end
+        end
+    end
+  end
+end

data/lib/rails/generators/ai/templates/agent.rb.tt

@@ -0,0 +1,11 @@
+<% module_namespacing do -%>
+class <%= class_name %> < ApplicationAI
+<% actions.each_with_index do |action, index| -%>
+<% if index != 0 -%>
+
+<% end -%>
+  def <%= action %>
+  end
+<% end -%>
+end
+<% end -%>

data/lib/rails/generators/ai/templates/application_agent.rb.tt

@@ -0,0 +1,5 @@
+<% module_namespacing do -%>
+class ApplicationAI < ActionAI::Agent
+  layout 'ai'
+end
+<% end %>

data/lib/ruby_llm/providers/test/echo.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Echo model behavior for the RubyLLM Test provider.
+    #
+    # A deterministic response builder (`#echo_response`) returns
+    # incoming prompt content.
+    #
+    # It is intended to be mixed into `RubyLLM::Providers::Test`.
+    module Test::Echo
+      def self.id = "echo"
+
+      def self.info = Model::Info.new(
+        id:,
+        name:,
+        provider:     Test.slug,
+        capabilities: Test.capabilities,
+
+        modalities: {
+          input:  %w[text],
+          output: %w[text],
+        },
+      )
+
+      private
+
+      def echo_response(messages, **) = {
+        content: RubyLLM.concat_content(messages.map(&:content)),
+      }
+    end
+  end
+
+  def self.concat_content *parts
+    strings, contents = parts
+        .flatten
+        .partition { it.is_a? String }
+
+    Content.new(
+      [*strings, *contents.map(&:text)]
+          .reject(&:empty?)
+          .join("\n\n"),
+      contents.sum([], &:attachments)
+          .map(&:source)
+    )
+  end
+end

data/lib/ruby_llm/providers/test.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module RubyLLM
+  module Providers
+    # In-memory provider intended for tests.
+    #
+    # This provider mirrors the behavior of a local fake adapter:
+    # - it does not initialize any remote connections,
+    # - it returns deterministic responses based on model-specific helpers
+    #   (for example, `echo_response` from `Test::Echo`).
+    class Test < Provider
+      autoload :Echo, "ruby_llm/providers/test/echo"
+
+      include Echo
+
+      def self.local? = true
+
+      def initialize(...)
+        # configuration not needed
+        # skip any connections
+      end
+
+      def complete(messages, model:, **)
+        Message.new(
+          role:     :assistant,
+          model_id: model.id,
+
+          **send("#{model.id}_response", messages)
+        ).tap do |message|
+          yield message.content if block_given?
+        end
+      end
+
+      def list_models = [Echo]
+          .map(&:info)
+    end
+  end
+end

data/lib/ruby_llm/tester.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "ruby_llm/providers/test"
+
+module RubyLLM
+  # == Testing with RubyLLM::Tester
+  #
+  # For tests, require +ruby_llm/tester+ to switch to an in-memory provider.
+  # It behaves like +Mail::TestMailer+ by collecting prompt interactions in an array:
+  #
+  #   require "ruby_llm/tester"
+  #
+  #   RubyLLM::Tester.interactions.clear
+  #
+  #   RubyLLM.chat.say "Hello!"
+  #
+  #   RubyLLM::Tester.interactions.size         # => 1
+  #   RubyLLM::Tester.interactions.last.role    # => :user
+  #   RubyLLM::Tester.interactions.last.content # => "Hello!"
+  #
+  # The test provider uses an +echo+ model and returns the prompt content back as
+  # the assistant response, so assertions stay deterministic and offline.
+  module Tester
+    mattr_reader :interactions, default: []
+
+    def self.register *messages
+      interactions.concat messages.flatten
+    end
+  end
+
+  Provider.register :test, Class.new(Providers::Test) {
+    def complete(messages, ...)
+      Tester.register messages
+
+      super
+    end
+  }
+
+  models.refresh!
+end