action_ai 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 026dc5bbd0ff082b147fc05e6e9e2784d0f89da393249857c383e38da57c79ac
-  data.tar.gz: ffeec65357f212fd305ad480a7a5f35c2b96ba9880acfcafbdaf437885f532b0
+  metadata.gz: 626b0d7eb4998d7c208dc99eb8e60932a3006988176bbd784935f1e00437b485
+  data.tar.gz: 97512e0c8fd015af6235d61b31ed36e7030702ddaf4b436b18b462b39013bd55
 SHA512:
-  metadata.gz: 742b0b2a62dc5ab713b5fa3cb64aa255a197835b0ef027f6e79bc0903f4c3497f1b13836a2792dfd75852423d08dd7fd65dbc81108c92d143b6f812a64ac9172
-  data.tar.gz: 9999ac05bfd4eca661dbe84156b2d06a8a6ab0006ae64d7bc2d2f0c334b125e62ea8ed4f03ba24c6248f90b0d305ca9848a10cfa19040c06815face10bdc251a
+  metadata.gz: 5721c21b4234b75cc9afce08eef6e5df89b4cb3364b75df8bbc3735c9ed3735d19fe6186d1893b678e5bfb9cddcbe15511909babd0ab7851f7663fd2c4fb1011
+  data.tar.gz: 025dec0b60c2b398450fe31174789df35689bef9a48a5c77627619c9df3c6fd2de62b153c968430a2135b0ca2cc9ee73e29049e502e5b34acbbd1217ba523fa4

data/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project will be documented in this file.
 
+
+## [0.3.0] - 2026-10-13
+
+### Changed
+
+- Moved to RubyLLM 2.
+- Dropped `echo` test model in favor of `echo` protocol.
+
+### Added
+
+#### Structured output
+
+- `.schema` class method on any `ActiveModel::API` model, returning a cached `Schematist::Schema` instance derived from the model’s attribute types and constraints.
+  - Include Active Record associations as nested schemas via objects/arrays.
+    Consider associations registered for _nested attributes_ only.
+  - Prefer custom schemas over inferred ones.
+    Define them as `<ModelName>Schema < ActionAI::Schema` classes under `app/schemas`.
+- `#returns(ModelClass)` instance method in agent actions: configures structured output via `chat.with_schema` and decorates the resulting `RubyLLM::Message` with `#object` returning a model instance.
+  - Use Strong Parameters to decorate returned JSON for security reasons.
+    AI model’s output shouldn’t be considered a trusted input.
+- `#returns([ModelClass])` array syntax: configures an array schema and `#object` returns an array of model instances.
+
+
+## [0.2.0] - 2026-06-30
+
+### Added
+
+- Implicit `ask` behavior for AI actions without explicit prompts, matching Action Controller-style ergonomics.
+- Action chaining, enabling users to construct complex AI workflows from discrete jobs.
+
+### Fixed
+
+- `echo` test model to support multiple chat interactions.
+
+
 ## [0.1.0] - 2026-05-05
 
 Refactored from Action Mailer.

data/README.rdoc

@@ -16,6 +16,8 @@ shape for AI interactions rather than building an unrelated API from scratch.
 
 The framework works by initializing any instance variables you want to be
 available in the prompt template.
+Like +render+ in Action Controller, the implicit +ask+ will be triggered
+automatically at the end of the action unless you have already called it.
 
 This can be as simple as:
 
@@ -25,10 +27,16 @@ This can be as simple as:
     def code(task, language)
       @task     = task
       @language = language
-      ask
     end
   end
 
+If you need to customize the prompt execution (e.g., pass options or a custom prompt),
+you can call +ask+ explicitly:
+
+  def run(spec_file)
+    ask "Run the attached spec", with: spec_file
+  end
+
 After the action method completes, the framework will automatically:
 1. Render the prompt from the corresponding template (e.g., +app/ai/prompts/generator/code.erb+)
 2. Send it to the configured AI model via +ask+
@@ -64,6 +72,22 @@ Or you can just chain the methods together like:
 
   Generator.code("Parse CSV and dedupe", :ruby).content  # Returns AI's response for the prompt
 
+You can also chain multiple agent actions to compose a small workflow before reading the final response:
+
+  class WorkflowAgent < ApplicationAI
+    def collect(topic)
+      @topic = topic
+      ask "Collect #{@topic}"
+    end
+
+    def refine(style:)
+      ask "Refine #{@topic} as #{style}"
+    end
+  end
+
+  WorkflowAgent.collect("release notes").refine(style: "bullet list").content
+  # => collected release notes refined as bullet list
+
 == Setting defaults
 
 It is possible to set default values that will be used in every method in your
@@ -93,6 +117,110 @@ The Agent class has the full list of configuration options. Here's an example:
   }
 
 
+== Structured output (data schemas)
+
+Action AI can instruct the model to return structured JSON that maps directly
+to an ActiveModel model. Two features cooperate to make this work:
+
+=== +.schema+ on ActiveModel models
+
+Any model that includes +ActiveModel::API+ automatically gains a +.schema+
+class method that returns a +Schematist::Schema+ instance derived from the model's
+attribute types.
+
+  class Person
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :name,  :string
+    attribute :age,   :integer
+    attribute :score, :float
+  end
+
+  Person.schema                         # => a Schematist::Schema instance
+  Person.schema.new.to_json_schema      # => {name: "Person", schema: {...}}
+
+Supported type mappings:
+
+* +:string+, +:immutable_string+, +:text+ → JSON +string+
+* +:integer+, +:big_integer+ → JSON +integer+
+* +:float+, +:decimal+, +:big_decimal+ → JSON +number+
+* +:boolean+ → JSON +boolean+
+* +:date+, +:datetime+, +:time+ → JSON +string+ with +format+ set to
+  +"date"+, +"date-time"+, or +"time"+ respectively
+* +:binary+ → JSON +string+ with +contentEncoding+ set to +"base64"+
+
+Other types are not included in the schema.
+
+Active Record associations are included as nested schemas via +object+/+array+.
+To prevent unnescessary nesting or circular dependencies, the schema will include
+associations registered for _nested attributes_ (via +accepts_nested_attributes_for+) only.
+
+=== +returns+ in agent actions
+
+Call +returns ModelClass+ inside an action method to declare the expected
+return type. Action AI will:
+
+1. Configure the chat to request output matching the model's JSON schema
+   (+chat.with_schema ModelClass.schema+).
+2. Decorate the resulting +RubyLLM::Message+ with Strong Parameters.
+3. Construct a model instance accessible via +#object+.
+
+  class Extractor < ApplicationAI
+    def person(text)
+      @text = text
+
+      returns Person do |params|
+        params.permit(:name, :age)
+      end
+    end
+  end
+
+  result = Extractor.person("Alice is 30 years old")
+  result.content  # => '{"name":"Alice","age":30}'
+  result.parsed   # => {"name" => "Alice", "age" => 30}
+  result.object   # => #<Person name="Alice" age=30>
+
+Pass the class wrapped in an array to declare an array return type:
+
+  class Extractor < ApplicationAI
+    def people(text)
+      @text = text
+
+      returns [Person] do |params|
+        params.permit(:name, :age)
+      end
+    end
+  end
+
+  result = Extractor.people("Alice is 30 and Bob is 25")
+  result.content  # => '[{"name":"Alice","age":30},{"name":"Bob","age":25}]'
+  result.parsed   # => [{"name" => "Alice", "age" => 30}, {"name" => "Bob", "age" => 25}]
+  result.object   # => [#<Person name="Alice" age=30>, #<Person name="Bob" age=25>]
+
+The schema is built from the model's declared attributes and cached.
+
+=== Custom schemas
+
+If an inferred schema is not sufficient, define a +Schematist::Schema+
+subclass under +app/schemas+ with the model's full class name followed by
++Schema+. Custom schemas are looked up first; models without a matching class
+continue to use the inferred schema.
+
+  # app/schemas/person_schema.rb
+  class PersonSchema < ActionAI::Schema
+    string :name
+    integer :age, minimum: 0
+  end
+
+For namespaced models, mirror the namespace in +app/schemas+:
+
+  # app/schemas/admin/person_schema.rb
+  class Admin::PersonSchema < ActionAI::Schema
+    string :name
+  end
+
+
 == Download and installation
 
 The latest version of Action AI can be installed with RubyGems:

data/lib/action_ai/agent.rb

@@ -278,6 +278,8 @@ module ActionAI
   #   <tt>execution_job</tt>. Agents can set this to use a custom queue name.
   class Agent < AbstractController::Base
     include Callbacks
+    include ImplicitInteraction
+    prepend StructuredOutput
     include QueuedExecution
     include Rescuable
     include Parameterized

data/lib/action_ai/implicit_interaction.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActionAI
+  # # Action AI Implicit Interaction
+  #
+  # Handles implicit interactions for an agent action that does not explicitly
+  # respond with `ask`.
+  #
+  # If no explicit `ask` is performed by the action, the implicit response is
+  # to call `ask` with the default prompt rendering.
+  module ImplicitInteraction
+    def send_action(...)
+      super
+        .tap { default_interaction unless performed? }
+    end
+
+    def default_interaction = ask
+  end
+end

data/lib/action_ai/interaction.rb

@@ -77,6 +77,23 @@ module ActionAI
     #   end
     def later(...) = enqueue_execution(...)
 
+    ruby2_keywords def method_missing(method, *args, &)
+      case method.name
+      when *@agent_class.action_methods
+        processed_agent.process(@action = method, *(@args = args), &)
+        self
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      [
+        method.name.in?(@agent_class.action_methods),
+        super,
+      ].any?
+    end
+
     private
       # Returns the processed Agent instance. We keep this instance
       # on hand so we can run callbacks and delegate exception handling to it.

data/lib/action_ai/model_schema/active_model.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "action_ai/refinements/regexp"
+
+module ActionAI
+  module ModelSchema
+    # Extends schema inference with Active Model–specific behavior.
+    #
+    # Overrides the base inference methods to extract constraint metadata
+    # from Active Model validation declarations (presence, inclusion,
+    # numericality, format, length, comparison, and acceptance).
+    module Inference::ActiveModel
+      using Refinements::Regexp
+
+      private
+
+      # Determines whether an attribute is required by checking for
+      # a presence validator, in addition to any other sources.
+      def attribute_required? name
+        super { [
+          attribute_validators(name, :presence)
+              .any?,
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # Infers enum values from inclusion and numericality validators
+      # that declare an `:in` option with multiple values.
+      def attribute_enum name
+        super { [
+          *[
+            *attribute_validators(name, :numericality),
+            *attribute_validators(name, :inclusion),
+          ].filter_map { it.options[:in] },
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # Infers a constant value from validators that restrict the
+      # attribute to a single value: comparison/equality, single-item
+      # inclusion, or acceptance validators without `allow_nil`.
+      def attribute_const name
+        super { [
+          *[
+            *attribute_validators(name, :comparison),
+            *attribute_validators(name, :numericality),
+          ].filter_map { it.options[:equal_to] },
+
+          *[
+            *attribute_validators(name, :inclusion),
+            *attribute_validators(name, :numericality),
+          ].filter_map { it.options[:in] }
+              .select(&:one?)
+              .map(&:first),
+
+          *attribute_validators(name, :acceptance)
+              .reject { it.options[:allow_nil] }
+              .presence
+              &.any?,
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # Infers a regex pattern from format validators, combining
+      # multiple patterns into a single expression.
+      # Validators with `:without` are negated.
+      def attribute_format name
+        super { [
+          *attribute_validators(name, :format)
+              .map(&:options)
+              .filter_map { it[:with] or ~it[:without] rescue nil },
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # Infers minimum and maximum string length from length validators.
+      def attribute_length name
+        super { [
+          *attribute_validators(name, :length)
+              .map(&:options)
+              .map { {
+                minimum: it.values_at(:is, :minimum).find(&:itself),
+                maximum: it.values_at(:is, :maximum).find(&:itself),
+              } },
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # Infers numeric boundaries (minimum, maximum, greater_than,
+      # less_than, multiple_of) from comparison and numericality validators.
+      def attribute_boundaries name
+        super { [
+          *[
+            *attribute_validators(name, :comparison),
+            *attribute_validators(name, :numericality),
+          ].map(&:options)
+              .map { {
+                minimum:      it[:greater_than_or_equal_to],
+                greater_than: it[:greater_than],
+                less_than:    it[:less_than],
+                maximum:      it[:less_than_or_equal_to],
+
+                multiple_of:  it[:multiple_of],
+              } },
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # Returns the validators for an attribute, optionally filtered
+      # by validator type (e.g., `:presence`, `:inclusion`, `:format`).
+      def attribute_validators name, type = nil
+        validators_on(name)
+            .grep(ActiveModel::Validations.const_get "#{type.to_s.camelize}Validator")
+      end
+    end
+  end
+end

data/lib/action_ai/model_schema/active_record.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ActionAI
+  module ModelSchema
+    # Extends schema inference with Active Record–specific behavior.
+    #
+    # Overrides the base inference methods to incorporate database column
+    # metadata (nullability, defaults, limits, decimal scale) and model-level
+    # features (defined enums, STI inheritance).
+    #
+    # Unlike the Active Model inference, which relies solely on validation
+    # declarations, this module reads the actual column schema to produce
+    # more precise constraints.
+    module Inference::ActiveRecord
+      include Memery
+
+      def foreign_keys = reflect_on_all_associations(:belongs_to)
+          .map(&:foreign_key)
+
+      def cache_columns = [
+          *(reflect_on_all_associations
+              .filter_map(&:counter_cache_column)
+          ),
+      ]
+
+      private
+
+      # Excludes DB-managed columns, since they are not typically part of the
+      # model’s input data.
+      def schema_attributes = super
+          .except(*[
+              *primary_key,
+              *foreign_keys.flatten,
+              :created_at, :updated_at,
+              locking_column,
+              *cache_columns,
+          ].map(&:to_sym))
+          .merge(schema_reflections)
+
+      memoize def schema_reflections = nested_attributes_options
+          .filter_map { |name, options|
+            reflection = reflect_on_association name
+
+            [ name, {
+              type:        reflection.collection? ? :array : :object,
+              of:          reflection.klass.schema,
+              description: try(:human_attribute_name, name),
+              required:    reflection_required?(name),
+              max_items:   options[:limit],
+            }.compact ]
+          }
+          .to_h
+
+      # Determines whether an attribute is required by checking the column’s
+      # null constraint, in addition to any Active Model checks.
+      def attribute_required? name
+        super { [
+          !column_for_attribute(name).null,
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # Returns the default value for an attribute from the column defaults.
+      def attribute_default name
+        column_defaults[name.to_s]
+      end
+
+      # Infers enum values from Active Record `enum` declarations and,
+      # for the inheritance column, includes valid STI class names (the base
+      # class and all descendants).
+      def attribute_enum name
+        super { [
+          defined_enums[name],
+
+          ([self, *descendants]
+              .map(&:name) if
+          name.to_s == inheritance_column),
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # Infers a constant value from acceptance validators that do not allow
+      # nil, but only for non-nullable columns.
+      def attribute_const name
+        super { [
+          *attribute_validators(name, :acceptance)
+              &.select { it.options[:allow_nil] }
+              .presence
+              &.any?,
+
+          *(yield if block_given?)
+        ] unless column_for_attribute(name).null }
+      end
+
+      # Infers the maximum string length from the column’s database limit.
+      def attribute_length name
+        super { [
+          {
+            maximum: column_for_attribute(name).limit
+          },
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      # For decimal columns, sets `multiple_of` based on the column scale
+      # (e.g., scale 2 → multiple_of 0.01), ensuring the generated schema
+      # rejects values with more decimal places than the column supports.
+      def attribute_boundaries name
+        super { [
+          {
+            multiple_of: column_for_attribute(name)
+                .then.detect { it.type == :decimal }
+                &.then { 10 ** (-it.scale) },
+          },
+
+          *(yield if block_given?)
+        ] }
+      end
+
+      def reflection_required? name
+        reflect_on_association(name)&.then do
+          case it
+          when ActiveRecord::Reflection::BelongsToReflection
+            not it.options[:optional]
+          when ActiveRecord::Reflection::HasOneReflection
+            it.options[:required] || false
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end