action_ai 0.2.0 → 0.4.0

data/lib/action_ai/model_schema/active_record.rb

@@ -0,0 +1,151 @@
+# 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(stored_attributes.values.reduce(:|).to_h do |name|
+            [ name, {
+              type:             :string,
+              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 ]
+          end)
+          .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&.detect(&:many?)
+
+      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.4.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/rails/generators/ai/templates/agent.rb.tt

@@ -1,5 +1,9 @@
 <% module_namespacing do -%>
 class <%= class_name %> < ApplicationAI
+  # Uncomment to configure model/instructions/tools using the RubyLLM agent DSL:
+  # model "gpt-6.1-sol"
+  # instructions "You are a helpful assistant."
+
 <% actions.each_with_index do |action, index| -%>
 <% if index != 0 -%>
 

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