action_prompter 0.1.0

data/lib/action_prompt/adapters/null.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActionPrompt
+  module Adapters
+    # A no-op adapter that silently discards all prompts and returns +nil+.
+    #
+    # Useful for disabling LLM calls in environments where you want to
+    # suppress all outbound requests (e.g., a staging environment without
+    # API credentials).
+    #
+    #   ActionPrompt.configure do |config|
+    #     config.adapter = ActionPrompt::Adapters::Null.new
+    #   end
+    class Null < Base
+      # @return [nil] always returns nil without making any external calls
+      def complete(prompt_text, options = {}) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+    end
+  end
+end

data/lib/action_prompt/adapters/test.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActionPrompt
+  module Adapters
+    # A test adapter that captures deliveries in memory without making real
+    # API calls. Use this in your test suite to assert on prompt content.
+    #
+    # == Setup (spec/support/action_prompt.rb)
+    #
+    #   RSpec.configure do |config|
+    #     config.before(:each) do
+    #       ActionPrompt.reset_configuration!
+    #       ActionPrompt::Adapters::Test.clear_deliveries!
+    #     end
+    #   end
+    #
+    # == Asserting on deliveries
+    #
+    #   it "sends the article body in the prompt" do
+    #     ArticleSummarizerPrompt.summarize(article).deliver_now
+    #
+    #     delivery = ActionPrompt::Adapters::Test.deliveries.last
+    #     expect(delivery[:prompt]).to include(article.body)
+    #     expect(delivery[:options][:model]).to eq("gpt-4o-mini")
+    #   end
+    class Test < Base
+      class << self
+        # All prompts delivered since the last {clear_deliveries!} call.
+        #
+        # Each entry is a Hash with keys:
+        #   - +:prompt+  — the rendered prompt string
+        #   - +:options+ — the merged LLM options hash
+        #
+        # @return [Array<Hash>]
+        def deliveries
+          @deliveries ||= []
+        end
+
+        # Clears all recorded deliveries. Call this in a +before(:each)+ block.
+        # @return [void]
+        def clear_deliveries!
+          @deliveries = []
+        end
+      end
+
+      # Records the delivery and returns a predictable canned response string.
+      #
+      # @param prompt_text [String]
+      # @param options [Hash]
+      # @return [String]
+      def complete(prompt_text, options = {})
+        delivery = { prompt: prompt_text, options: options }
+        self.class.deliveries << delivery
+        "[ActionPrompt::Test] Response for #{options[:model] || "unknown-model"} " \
+          "(#{prompt_text.length} chars)"
+      end
+    end
+  end
+end

data/lib/action_prompt/base.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module ActionPrompt
+  # Base class for all prompt classes. Subclass this to define your prompts.
+  #
+  # Each public instance method in a subclass is a "prompt action". Calling
+  # the method at the class level returns an {ActionPrompt::Message} that can
+  # be delivered synchronously via {ActionPrompt::Message#deliver_now}.
+  #
+  # == Defining a prompt
+  #
+  #   class ArticleSummarizerPrompt < ActionPrompt::Base
+  #     # Class-level defaults override the global config for this class only.
+  #     default model: "gpt-4o-mini", temperature: 0.5
+  #
+  #     def summarize(article)
+  #       @article = article          # available in the ERB template as @article
+  #       @word_limit = 150
+  #
+  #       prompt(model: "gpt-4o")     # optional per-action override
+  #     end
+  #   end
+  #
+  # == Delivering a prompt
+  #
+  #   response = ArticleSummarizerPrompt.summarize(article).deliver_now
+  #
+  # == Template location
+  #
+  #   app/views/action_prompts/article_summarizer_prompt/summarize.text.erb
+  #
+  class Base
+    # Inheritable hash of default LLM options for the class.
+    # Set via the {.default} class macro.
+    class_attribute :default_options, default: {}, instance_accessor: false
+
+    # ActionView path set populated by the Railtie (or set manually in tests).
+    class_attribute :view_paths, default: ActionView::PathSet.new, instance_accessor: false
+
+    class << self
+      # Sets default LLM options for all actions within this class.
+      # Options merge with the global config, and can be further overridden
+      # per-action by passing options to {#prompt}.
+      #
+      # @param options [Hash] e.g. +model: "gpt-4o", temperature: 0.7+
+      # @return [void]
+      #
+      # @example
+      #   class MyPrompt < ActionPrompt::Base
+      #     default model: "gpt-4o", temperature: 0.3
+      #   end
+      def default(**options)
+        self.default_options = default_options.merge(options)
+      end
+
+      # Intercepts calls to public instance methods (prompt actions) and
+      # returns an {ActionPrompt::Message}. This is the primary entry point
+      # for building a prompt from outside the class.
+      #
+      # @example
+      #   ArticleSummarizerPrompt.summarize(article)  # => ActionPrompt::Message
+      #
+      # @return [ActionPrompt::Message]
+      def method_missing(method_name, *args, &block)
+        if public_method_defined?(method_name)
+          instance = new
+          instance.send(:process, method_name, *args, &block)
+          instance.message
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        public_method_defined?(method_name) || super
+      end
+    end
+
+    # The {ActionPrompt::Message} built by the most recent call to {#prompt}.
+    # @return [ActionPrompt::Message, nil]
+    attr_reader :message
+
+    # Declares per-action LLM options and finalises the {Message} for this
+    # action. Call this at the end of every action method.
+    #
+    # Options are merged in increasing priority order:
+    #   global config defaults < class-level defaults < per-action options
+    #
+    # @param options [Hash] per-action overrides (e.g. +model:+, +temperature:+)
+    # @return [ActionPrompt::Message]
+    def prompt(options = {})
+      merged_options = ActionPrompt.configuration.default_options
+                                   .merge(self.class.default_options)
+                                   .merge(options)
+      @message = Message.new(self, @_action_name, merged_options)
+    end
+
+    private
+
+    # Runs an action method by name and ensures a {Message} is available.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @return [ActionPrompt::Message]
+    def process(method_name, *args)
+      @_action_name = method_name.to_s
+      @message = nil
+      public_send(method_name, *args)
+
+      # Guard: if the developer forgot to call `prompt` in their action,
+      # build a message with default options so deliver_now still works.
+      @message ||= Message.new(self, @_action_name,
+                               ActionPrompt.configuration.default_options
+                                           .merge(self.class.default_options))
+    end
+  end
+end

data/lib/action_prompt/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActionPrompt
+  # Holds global configuration for the ActionPrompt framework.
+  #
+  # Configure via an initializer:
+  #
+  #   # config/initializers/action_prompt.rb
+  #   ActionPrompt.configure do |config|
+  #     config.adapter = MyOpenAIAdapter.new(api_key: ENV.fetch("OPENAI_API_KEY"))
+  #     config.default_options = { model: "gpt-4o", temperature: 0.7 }
+  #   end
+  class Configuration
+    # The active delivery adapter. Defaults to the Test adapter.
+    # @return [ActionPrompt::Adapters::Base]
+    attr_accessor :adapter
+
+    # Global default options passed to every adapter call unless overridden.
+    # @return [Hash]
+    attr_accessor :default_options
+
+    # Logger instance. Defaults to Rails.logger inside a Rails app.
+    # @return [Logger]
+    attr_accessor :logger
+
+    def initialize
+      @adapter = ActionPrompt::Adapters::Test.new
+      @default_options = {}
+      @logger = default_logger
+    end
+
+    private
+
+    def default_logger
+      defined?(Rails) ? Rails.logger : Logger.new($stdout, level: Logger::INFO)
+    end
+  end
+end

data/lib/action_prompt/message.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ActionPrompt
+  # Represents a fully prepared prompt ready for delivery to an LLM adapter.
+  # Analogous to +Mail::Message+ in ActionMailer.
+  #
+  # Instances are returned by calling a class-level action method:
+  #
+  #   message = ArticleSummarizerPrompt.summarize(article)
+  #   message.body       # => rendered ERB string (lazily evaluated)
+  #   message.deliver_now  # => LLM response string
+  class Message
+    # The prompt instance that built this message.
+    # @return [ActionPrompt::Base]
+    attr_reader :prompt_instance
+
+    # The name of the action that built this message.
+    # @return [String]
+    attr_reader :action_name
+
+    # Merged LLM options (global defaults < class defaults < per-action options).
+    # @return [Hash]
+    attr_reader :options
+
+    # @param prompt_instance [ActionPrompt::Base]
+    # @param action_name [String]
+    # @param options [Hash]
+    def initialize(prompt_instance, action_name, options = {})
+      @prompt_instance = prompt_instance
+      @action_name = action_name
+      @options = options
+    end
+
+    # The rendered prompt body. Evaluated lazily on first access.
+    #
+    # @return [String]
+    def body
+      @body ||= Renderer.new(prompt_instance, action_name).render
+    end
+
+    # Delivers the prompt to the configured adapter synchronously and returns
+    # the LLM response.
+    #
+    # @return [String, nil] the LLM's response (type depends on the adapter)
+    def deliver_now
+      log_delivery
+      ActionPrompt.configuration.adapter.complete(body, options)
+    end
+
+    # Enqueues the prompt for asynchronous delivery via ActiveJob.
+    #
+    # @note Full ActiveJob integration is planned for a future release.
+    #   This currently raises +NotImplementedError+.
+    # @raise [NotImplementedError]
+    def deliver_later(**_kwargs)
+      raise NotImplementedError,
+            "deliver_later is not yet implemented. Use deliver_now. " \
+            "ActiveJob integration is planned for a future release."
+    end
+
+    # @return [String]
+    def inspect
+      "#<ActionPrompt::Message action=#{action_name.inspect} options=#{options.inspect}>"
+    end
+
+    alias to_s inspect
+
+    private
+
+    def log_delivery
+      logger = ActionPrompt.configuration.logger
+      return unless logger
+
+      logger.debug do
+        "[ActionPrompt] Delivering #{prompt_instance.class.name}##{action_name} " \
+          "via #{ActionPrompt.configuration.adapter.class.name} " \
+          "with options #{options.inspect}"
+      end
+    end
+  end
+end

data/lib/action_prompt/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ActionPrompt
+  class Railtie < Rails::Railtie
+    # Ensure app/prompts is part of the autoload paths so prompt classes
+    # are loaded by Zeitwerk without any extra configuration.
+    initializer "action_prompt.add_autoload_paths" do |app|
+      prompts_path = app.root.join("app", "prompts").to_s
+
+      app.config.autoload_paths      << prompts_path
+      app.config.eager_load_paths    << prompts_path
+    end
+
+    # Point ActionPrompt::Base's view paths at the application's view directory
+    # so ERB templates resolve correctly from app/views/action_prompts/.
+    initializer "action_prompt.configure_view_paths" do |app|
+      ActiveSupport.on_load(:action_prompt) do
+        ActionPrompt::Base.view_paths = ActionView::PathSet.new(
+          [app.root.join("app", "views").to_s]
+        )
+      end
+    end
+
+    # Use Rails.logger once the app is fully initialized.
+    initializer "action_prompt.set_logger" do
+      ActiveSupport.on_load(:action_prompt) do
+        ActionPrompt.configuration.logger = Rails.logger
+      end
+    end
+
+    # Allow prompt classes to call run_load_hooks in the future.
+    ActiveSupport.run_load_hooks(:action_prompt, Base)
+  end
+end

data/lib/action_prompt/renderer.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ActionPrompt
+  # Handles ERB template rendering for prompt actions via ActionView.
+  #
+  # Templates are resolved from the view paths configured on the prompt class
+  # (defaults to +app/views/+ in a Rails app). The lookup path convention is:
+  #
+  #   app/views/action_prompts/<prompt_class_name>/<action_name>.text.erb
+  #
+  # == Examples
+  #
+  #   ArticleSummarizerPrompt  ->  action_prompts/article_summarizer_prompt/summarize.text.erb
+  #   Admin::ReportPrompt      ->  action_prompts/admin/report_prompt/generate.text.erb
+  class Renderer
+    # @param prompt_instance [ActionPrompt::Base] owns the instance variables for the template
+    # @param action_name [String] the prompt action method name
+    def initialize(prompt_instance, action_name)
+      @prompt_instance = prompt_instance
+      @action_name = action_name
+    end
+
+    # Renders the ERB template and returns the resulting string.
+    #
+    # @return [String] the rendered prompt body
+    # @raise [ActionView::MissingTemplate] if the template file cannot be found
+    def render
+      lookup_context = ActionView::LookupContext.new(resolved_view_paths)
+      view = ActionView::Base.with_empty_template_cache.new(lookup_context, assigns, nil)
+      view.render(template: template_path, formats: [:text], handlers: [:erb])
+    end
+
+    private
+
+    # Derives the template path from the prompt class name and action.
+    #
+    # @return [String] e.g. "action_prompts/article_summarizer_prompt/summarize"
+    def template_path
+      class_segment = @prompt_instance.class.name
+                                      .gsub("::", "/")
+                                      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                                      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                                      .downcase
+
+      "action_prompts/#{class_segment}/#{@action_name}"
+    end
+
+    # Returns the view paths configured on the prompt class, falling back to
+    # the Rails app root or the current working directory.
+    #
+    # @return [Array<String>]
+    def resolved_view_paths
+      class_paths = @prompt_instance.class.view_paths.to_a.map(&:to_s)
+      return class_paths unless class_paths.empty?
+
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        [Rails.root.join("app", "views").to_s]
+      else
+        [File.expand_path("app/views", Dir.pwd)]
+      end
+    end
+
+    # Collects public instance variables from the prompt, exposing them
+    # to the ERB template as top-level assigns.
+    #
+    # Variables prefixed with +_+ or named +message+ are excluded.
+    #
+    # @return [Hash{String => Object}]
+    def assigns
+      @prompt_instance.instance_variables.each_with_object({}) do |ivar, hash|
+        name = ivar.to_s.delete_prefix("@")
+        next if name.start_with?("_") || name == "message"
+
+        hash[name] = @prompt_instance.instance_variable_get(ivar)
+      end
+    end
+  end
+end

data/lib/action_prompt/version.rb

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

data/lib/action_prompt.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/string/inflections"
+require "action_view"
+
+require_relative "action_prompt/version"
+require_relative "action_prompt/adapters/base"
+require_relative "action_prompt/adapters/null"
+require_relative "action_prompt/adapters/test"
+require_relative "action_prompt/configuration"
+require_relative "action_prompt/renderer"
+require_relative "action_prompt/message"
+require_relative "action_prompt/base"
+
+# ActionPrompt is an ActionMailer-inspired framework for defining, rendering,
+# and delivering LLM prompts in Ruby on Rails applications.
+#
+# == Configuration
+#
+#   ActionPrompt.configure do |config|
+#     config.adapter = MyAdapter.new(api_key: ENV.fetch("MY_API_KEY"))
+#     config.default_options = { model: "gpt-4o", temperature: 0.7 }
+#   end
+#
+# == Delivery
+#
+#   response = ArticleSummarizerPrompt.summarize(article).deliver_now
+#
+module ActionPrompt
+  class << self
+    # Returns the global configuration object.
+    # @return [ActionPrompt::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the {Configuration} for block-style setup.
+    # @yieldparam config [ActionPrompt::Configuration]
+    # @return [void]
+    def configure
+      yield configuration
+    end
+
+    # Resets configuration to defaults. Primarily useful in test suites.
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require_relative "action_prompt/railtie" if defined?(Rails::Railtie)

data/lib/generators/action_prompt/action_prompt_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/named_base"
+
+module ActionPrompt
+  # Rails generator that creates a prompt class and its ERB view templates.
+  #
+  # == Usage
+  #
+  #   rails generate action_prompt NAME [action action ...]
+  #
+  # == Examples
+  #
+  #   rails generate action_prompt ArticleSummarizer summarize
+  #   rails generate action_prompt Moderation classify flag
+  #   rails generate action_prompt Admin::Report generate
+  #
+  # Each invocation creates:
+  #   * app/prompts/<name>_prompt.rb
+  #   * app/views/action_prompts/<name>_prompt/<action>.text.erb  (one per action)
+  class ActionPromptGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path("templates", __dir__)
+
+    argument :actions,
+             type: :array,
+             default: [],
+             banner: "action action ..."
+
+    desc "Creates an ActionPrompt prompt class and ERB view template(s)."
+
+    # ------------------------------------------------------------------ #
+    # Steps
+    # ------------------------------------------------------------------ #
+
+    def create_prompt_file
+      template "prompt.rb.tt",
+               File.join("app/prompts", class_path, "#{file_name}_prompt.rb")
+    end
+
+    def create_view_files
+      actions.each do |action|
+        @current_action = action
+        template "prompt.text.erb.tt",
+                 File.join("app/views/action_prompts", class_path,
+                           "#{file_name}_prompt", "#{action}.text.erb")
+      end
+    end
+
+    private
+
+    # Full CamelCase class name including the "Prompt" suffix.
+    # @return [String] e.g. "ArticleSummarizerPrompt"
+    def prompt_class_name
+      "#{class_name}Prompt"
+    end
+
+    attr_reader :current_action
+  end
+end

data/lib/generators/action_prompt/templates/prompt.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class <%= prompt_class_name %> < ActionPrompt::Base
+  # Set class-level defaults. These override the global config for this class.
+  # default model: "gpt-4o-mini", temperature: 0.7
+<% actions.each do |action| -%>
+
+  def <%= action %>
+    # Assign instance variables here; they will be available in the ERB template.
+    # e.g.  @record = some_argument
+
+    prompt(
+      # model: "gpt-4o-mini",
+      # temperature: 0.7
+    )
+  end
+<% end -%>
+end

data/lib/generators/action_prompt/templates/prompt.text.erb.tt

@@ -0,0 +1,13 @@
+<%# app/views/action_prompts/<%= file_name %>_prompt/<%= current_action %>.text.erb %>
+<%# Instance variables set in <%= prompt_class_name %>#<%= current_action %> are available here. %>
+
+You are a helpful assistant.
+
+<%# TODO: Write your prompt below, referencing instance variables as needed. %>
+<%# Example:
+  Please summarize the following content in three bullet points:
+
+  Title: <%= @record.title %>
+
+  <%= @record.body %>
+%>