action_ai 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5b0c31e7ae5b9944a95f32563d3873adea7134ea32e11ebfc5dbc2a81eafec9
-  data.tar.gz: d20750877288e1e1306a58a08f6b1aeea02985d749df8ce763262e0cc68314e6
+  metadata.gz: 626b0d7eb4998d7c208dc99eb8e60932a3006988176bbd784935f1e00437b485
+  data.tar.gz: 97512e0c8fd015af6235d61b31ed36e7030702ddaf4b436b18b462b39013bd55
 SHA512:
-  metadata.gz: 84b92d55d7310f17e3746457cd76ecdae5dbed20aee80276b61d30824b38093d13c3f4753b69925e819dac9471bcfd5d1c1733aa46c78dd68969d0350c24a0c7
-  data.tar.gz: 0bbec9e620ec3fa03151b8dc4d6223b8a1de5d6b18cb4731c96df73d1bd2a9fb25a862c4dc3cbe27093468376a61c90d32f6763ef95f88f9c2f78118a077934e
+  metadata.gz: 5721c21b4234b75cc9afce08eef6e5df89b4cb3364b75df8bbc3735c9ed3735d19fe6186d1893b678e5bfb9cddcbe15511909babd0ab7851f7663fd2c4fb1011
+  data.tar.gz: 025dec0b60c2b398450fe31174789df35689bef9a48a5c77627619c9df3c6fd2de62b153c968430a2135b0ca2cc9ee73e29049e502e5b34acbbd1217ba523fa4

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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
@@ -13,6 +36,7 @@ All notable changes to this project will be documented in this file.
 
 - `echo` test model to support multiple chat interactions.
 
+
 ## [0.1.0] - 2026-05-05
 
 Refactored from Action Mailer.

data/README.rdoc

@@ -117,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

@@ -279,6 +279,7 @@ module ActionAI
   class Agent < AbstractController::Base
     include Callbacks
     include ImplicitInteraction
+    prepend StructuredOutput
     include QueuedExecution
     include Rescuable
     include Parameterized

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

data/lib/action_ai/model_schema.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "schematist"
+require "active_support/concern"
+require "action_ai/schema"
+require "action_ai/refinements/numeric"
+
+module ActionAI
+  # = Action AI Model Schema
+  #
+  # Adds a +.schema+ class method to any model that includes
+  # +ActiveModel::AttributeRegistration+. The returned schema is a
+  # +Schematist::Schema+ instance derived from the model's attribute types,
+  # suitable for use with +RubyLLM::Chat#with_schema+ and
+  # +ActionAI::Agent#returns+.
+  #
+  # Inject this module once (e.g., via the Railtie) and every ActiveModel class
+  # defined afterwards will gain +.schema+ automatically:
+  #
+  #   ActiveModel::API.include ActionAI::ModelSchema
+  #
+  # == Type mapping
+  #
+  # ActiveModel attribute types are mapped to JSON Schema types as follows:
+  #
+  # * +:string+, +:immutable_string+, +:text+ → +string+
+  # * +:integer+, +:big_integer+ → +integer+
+  # * +:float+, +:decimal+, +:big_decimal+ → +number+
+  # * +:boolean+ → +boolean+
+  # * +:binary+ → +string+ with +contentEncoding: "base64"+
+  # * +:date+, +:datetime+, +:time+ → +string+ with the corresponding
+  #   JSON Schema +format+
+  #
+  # Other types are omitted from the schema.
+  module ModelSchema
+    extend ActiveSupport::Concern
+    extend Schematist::Helpers
+
+    module Inference
+      autoload :ActiveModel,  "action_ai/model_schema/active_model"
+      autoload :ActiveRecord, "action_ai/model_schema/active_record"
+    end
+
+    TYPES = {
+      string:           :string,
+      immutable_string: :string,
+      text:             :string,
+      integer:          :integer,
+      big_integer:      :integer,
+      float:            :number,
+      decimal:          :number,
+      big_decimal:      :number,
+      boolean:          :boolean,
+      date:             :string,
+      datetime:         :string,
+      time:             :string,
+      binary:           :string,
+    }.freeze
+
+    FORMATS = {
+      date:     "date",
+      datetime: "date-time",
+      time:     "time",
+    }.freeze
+
+    ENCODINGS = {
+      binary: "base64",
+    }.freeze
+
+    included do
+      extend Inference::ActiveModel  if defined? ActiveModel  and self <= ActiveModel::Validations
+      extend Inference::ActiveRecord if defined? ActiveRecord and self <= ActiveRecord::Base
+    end
+
+    def self.new(...) = schema(...)
+
+    class_methods do
+      include Memery
+      using   Refinements::Numeric
+
+      # Returns a cached +Schematist::Schema+ instance derived from this
+      # model's attribute types.
+      #
+      # Numeric constraints and enum-like metadata are inferred from model
+      # validations when Rails exposes them, even when the validator itself is
+      # not actively enforced. In particular, +multiple_of+ is accepted by the
+      # schema generator here for JSON Schema output, even though
+      # +ActiveModel::Validations::NumericalityValidator+ ignores it at runtime.
+      memoize def schema = find_schema || build_schema
+
+      def find_schema = Schema.for(self)
+          &.new
+
+      def build_schema
+        attributes = schema_attributes
+
+        ModelSchema.new schema_name, **{
+          description: try(:model_name)&.human,
+        } do
+          attributes.each do |name, options|
+            send options.delete(:type), name, **options
+          end
+        end
+      end
+
+      memoize def to_json_schema = schema.to_json_schema
+        .with_indifferent_access
+
+      private
+
+      def schema_name = "#{name}Schema"
+
+      memoize def schema_attributes = attribute_types
+          .symbolize_keys
+          .transform_values(&:type)
+          .filter_map { |name, type|
+            [ name, {
+              type:             (TYPES[type] or next),
+              format:           FORMATS[type],
+              content_encoding: ENCODINGS[type],
+              description:      try(:human_attribute_name, name),
+              required:         attribute_required?(name),
+              default:          attribute_default(name),
+              enum:             attribute_enum(name),
+              const:            attribute_const(name),
+              pattern:          attribute_format(name),
+
+              **attribute_length(name),
+              **attribute_boundaries(name),
+            }.compact ]
+          }
+          .to_h
+
+      def attribute_types = raise NotImplementedError
+
+      def attribute_required?(name) = [
+        *(yield if block_given?)
+      ].any?
+
+      def attribute_default(name) = default_instance.send name
+
+      def attribute_enum(name) = [
+        *(yield if block_given?)
+      ].compact.presence
+          &.map(&:to_a)
+          &.inject(&:&)
+          &.then&.select(&:many?)&.first
+
+      def attribute_const(name) = [
+        *(yield if block_given?)
+      ].compact.presence
+          &.uniq
+          &.sole
+
+      def attribute_format(name) = [
+        *(yield if block_given?)
+      ].compact.presence
+          &.then { return it.first if it.one? }
+          &.map { "(?=.*#{it})" }
+          &.join
+          &.then { Regexp.new "\\A#{it}" }
+
+      def attribute_length(name) = [
+        *(yield if block_given?)
+      ].map { it.values_at :minimum, :maximum }
+          .transpose
+          .map(&:compact)
+          .map(&:presence)
+          .then do |(minimums, maximums)|
+            {
+              min_length: minimums&.max,
+              max_length: maximums&.min,
+            }
+          end
+
+      def attribute_boundaries(name) = [
+        *(yield if block_given?)
+      ].map { it.values_at :minimum, :maximum, :greater_than, :less_than, :multiple_of }
+          .transpose
+          .map(&:compact)
+          .map(&:presence)
+          .then do |(minimums, maximums, lowers, uppers, multiples)|
+            {
+              minimum:      minimums&.max,
+              maximum:      maximums&.min,
+              greater_than: lowers&.max,
+              less_than:    uppers&.min,
+              multiple_of:  multiples&.reduce(&:lcm),
+            }
+          end
+
+      memoize def default_instance = new
+    end
+  end
+end

data/lib/action_ai/railtie.rb

@@ -19,6 +19,10 @@ module ActionAI
       ActiveSupport.on_load(:action_ai) { self.logger ||= Rails.logger }
     end
 
+    initializer "action_ai.active_model_schema", before: :eager_load! do
+      ActiveModel::API.include ModelSchema if defined? ActiveModel
+    end
+
     initializer "action_ai.set_configs" do |app|
       paths   = app.config.paths
       options = app.config.action_ai
@@ -55,8 +59,11 @@ module ActionAI
     end
 
     initializer "action_ai.set_autoload_paths", before: :set_autoload_paths do |app|
+      app.config.paths.add "app/ai/agents",    autoload: true, eager_load: true
+      app.config.paths.add "test/ai/previews", autoload: true
+
       options = app.config.action_ai
-      app.config.paths["test/ai/prompts/previews"].concat(options.preview_paths)
+      app.config.paths["test/ai/previews"].concat(options.preview_paths)
     end
 
     config.after_initialize do |app|

data/lib/action_ai/refinements/numeric.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActionAI
+  module Refinements
+    module Numeric
+      refine ::Numeric do
+        def lcm other
+          m = [ self, other ]
+              .grep_v(Integer)
+              .map(&:rationalize)
+              .map(&:denominator)
+              .reduce(&:*)
+
+          [ self, other ]
+              .map { it * m }
+              .map(&:to_i)
+              .reduce(&:lcm)
+              .send(other.is_a?(Integer) ? :/ : :fdiv, m)
+        end
+      end
+
+      refine ::Integer do
+        def lcm other
+          return other.lcm self unless
+              other.is_a? Integer
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/action_ai/refinements/regexp.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActionAI
+  module Refinements
+    module Regexp
+      refine ::Regexp do
+        def ~@
+          self.class.new "\\A(?:(?!#{source}).)*\\z", options
+        end
+      end
+    end
+  end
+end

data/lib/action_ai/schema.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "schematist"
+require "magic/lookup"
+
+module ActionAI
+  class Schema < Schematist::Schema
+    extend Magic::Lookup
+
+    class << self
+      def name_for object_class
+        object_class
+          .to_s
+          .delete_suffix('Model')
+          .delete_suffix('Record')
+          .concat('Schema')
+      end
+    end
+  end
+end

data/lib/action_ai/structured_output.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "action_controller/metal/strong_parameters"
+
+module ActionAI
+  module StructuredOutput
+    def ask(*, as: @model_class, **, &)
+      super(*, **, &)&.tap do |message|
+        model_class = as or next
+
+        object = message.parsed&.then do |params|
+          case model_class
+          when Array
+            params.map { model_class.sole.new process_response_params(it) }
+          else
+            model_class.new process_response_params(params)
+          end
+        end
+
+        message.define_singleton_method(:object) { object }
+      end
+    end
+
+    # Declares the structured return type for this action. Configures the chat
+    # to request output matching the model's schema, and decorates the resulting
+    # +RubyLLM::Message+ with +#object+ accessor.
+    #
+    # Call +returns+ inside an action method before +ask+ (or before the
+    # implicit ask) to indicate which ActiveModel class the LLM should fill in:
+    #
+    #   class Extractor < ApplicationAI
+    #     def person(text)
+    #       @text = text
+    #       returns Person do |params|
+    #         params.permit(:name, :age)
+    #       end
+    #     end
+    #   end
+    #
+    # After execution:
+    #
+    #   response = Extractor.person("Alice is 30 years old")
+    #   response.content # => '{"name":"Alice","age":30}'
+    #   response.parsed  # => {"name" => "Alice", "age" => 30}
+    #   response.object  # => #<Person name="Alice" age=30>
+    #
+    # Pass an array with a single element 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
+    #
+    # After execution:
+    #
+    #   response = Extractor.people("Alice is 30 and Bob is 25")
+    #   response.content # => '[{"name":"Alice","age":30},{"name":"Bob","age":25}]'
+    #   response.parsed  # => [{"name" => "Alice", "age" => 30}, {"name" => "Bob", "age" => 25}]
+    #   response.object  # => [#<Person name="Alice" age=30>, #<Person name="Bob" age=25>]
+    #
+    # The +model_class+ must respond to +.schema+, which is automatically
+    # available on any model that includes +ActiveModel::Attributes+.
+    def returns model_class, &process_response_params
+      chat.with_schema case @model_class = model_class
+      when Array
+        { type: "array", items: model_class.sole.to_json_schema }
+      else
+        model_class.schema
+      end
+
+      @process_response_params = process_response_params
+    end
+
+    private
+
+    def process_response_params params
+      ActionController::Parameters.new(params)
+          .then(&(@process_response_params || :itself))
+    end
+  end
+end

data/lib/action_ai/version.rb

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

data/lib/action_ai.rb

@@ -27,6 +27,8 @@ require "abstract_controller"
 require "action_ai/version"
 require "action_ai/deprecator"
 
+require "ruby_llm"
+
 # Common Active Support usage in Action AI
 require "active_support"
 require "active_support/rails"
@@ -41,6 +43,8 @@ module ActionAI
 
   autoload :Agent
   autoload :Callbacks
+  autoload :Schema
+  autoload :ModelSchema
   autoload :PromptHelper
   autoload :Parameterized
   autoload :Preview
@@ -49,6 +53,7 @@ module ActionAI
   autoload :TestHelper
   autoload :Interaction
   autoload :ImplicitInteraction
+  autoload :StructuredOutput
   autoload :ExecutionJob
   autoload :QueuedExecution
 

data/lib/ruby_llm/protocols/echo.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module RubyLLM
+  module Protocols
+    # An in-memory protocol that returns the current prompt as the response.
+    class Echo < Protocol
+      def complete(messages, **)
+        Message.new(
+          role: :assistant,
+          model: model.id,
+
+          content: messages
+            .reverse_each.take_while { it.role != :assistant }.reverse
+            .map(&:content)
+            .compact_blank
+            .join("\n\n"),
+
+          attachments: messages
+            .sum([], &:attachments),
+        ).tap { yield it if block_given? }
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/test.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "ruby_llm"
+require "ruby_llm/protocols/echo"
 
 module RubyLLM
   module Providers
@@ -8,33 +9,16 @@ module RubyLLM
     #
     # 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`).
+    # - it returns deterministic responses through `echo` protocol.
     class Test < Provider
-      autoload :Echo, "ruby_llm/providers/test/echo"
-
-      include Echo
+      protocol :echo, Protocols::Echo
 
       def self.local? = true
 
-      def initialize(...)
-        # configuration not needed
+      def initialize(config)
+        @config = config
         # 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

@@ -18,7 +18,7 @@ module RubyLLM
   #   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 test provider uses an +echo+ protocol and returns the prompt content as
   # the assistant response, so assertions stay deterministic and offline.
   module Tester
     mattr_reader :interactions, default: []
@@ -28,7 +28,7 @@ module RubyLLM
     end
   end
 
-  Provider.register :test, Class.new(Providers::Test) {
+  Protocols::Echo.prepend Module.new {
     def complete(messages, ...)
       Tester.register messages
 
@@ -36,5 +36,9 @@ module RubyLLM
     end
   }
 
-  models.refresh!
+  Provider.register :test, Providers::Test
+
+  configure do |config|
+    config.model_registry_file = "test/models.json"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_ai
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
   - Alexander Senko
@@ -75,6 +75,22 @@ dependencies:
             version: "0"
   - !ruby/object:Gem::Dependency
     name: ruby_llm
+    requirement: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ~>
+          - !ruby/object:Gem::Version
+            version: "2.0"
+    type: :runtime
+    prerelease: false
+    version_requirements: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ~>
+          - !ruby/object:Gem::Version
+            version: "2.0"
+  - !ruby/object:Gem::Dependency
+    name: magic-lookup
     requirement: !ruby/object:Gem::Requirement
       requirements:
         -
@@ -138,12 +154,19 @@ files:
   - lib/action_ai/implicit_interaction.rb
   - lib/action_ai/interaction.rb
   - lib/action_ai/log_subscriber.rb
+  - lib/action_ai/model_schema.rb
+  - lib/action_ai/model_schema/active_model.rb
+  - lib/action_ai/model_schema/active_record.rb
   - lib/action_ai/parameterized.rb
   - lib/action_ai/preview.rb
   - lib/action_ai/prompt_helper.rb
   - lib/action_ai/queued_execution.rb
   - lib/action_ai/railtie.rb
+  - lib/action_ai/refinements/numeric.rb
+  - lib/action_ai/refinements/regexp.rb
   - lib/action_ai/rescuable.rb
+  - lib/action_ai/schema.rb
+  - lib/action_ai/structured_output.rb
   - lib/action_ai/test_case.rb
   - lib/action_ai/test_helper.rb
   - lib/action_ai/version.rb
@@ -151,16 +174,16 @@ files:
   - lib/rails/generators/ai/ai_generator.rb
   - lib/rails/generators/ai/templates/agent.rb.tt
   - lib/rails/generators/ai/templates/application_agent.rb.tt
+  - lib/ruby_llm/protocols/echo.rb
   - lib/ruby_llm/providers/test.rb
-  - lib/ruby_llm/providers/test/echo.rb
   - lib/ruby_llm/tester.rb
 homepage: "https://github.com/Alexander-Senko/action_ai"
 licenses:
   - MIT
 metadata:
   bug_tracker_uri: "https://github.com/Alexander-Senko/action_ai/issues"
-  changelog_uri: "https://github.com/Alexander-Senko/action_ai/blob/v0.2.0/CHANGELOG.md"
-  source_code_uri: "https://github.com/Alexander-Senko/action_ai/tree/v0.2.0"
+  changelog_uri: "https://github.com/Alexander-Senko/action_ai/blob/v0.3.0/CHANGELOG.md"
+  source_code_uri: "https://github.com/Alexander-Senko/action_ai/tree/v0.3.0"
   rubygems_mfa_required: "true"
 rdoc_options: []
 require_paths:

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

@@ -1,50 +0,0 @@
-# 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
-                     .reverse_each.take_while { it.role != :assistant }.reverse
-                     .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