action_ai 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5b0c31e7ae5b9944a95f32563d3873adea7134ea32e11ebfc5dbc2a81eafec9
-  data.tar.gz: d20750877288e1e1306a58a08f6b1aeea02985d749df8ce763262e0cc68314e6
+  metadata.gz: 3fa6d979d2013779ecfe3932a2c1bb04158dd99072ef5eb4b802f2ece910b34d
+  data.tar.gz: 46cb4d1ad9cca9f63c7af8d575abe3ad23fef1359d2f5d445617662e071b1ef6
 SHA512:
-  metadata.gz: 84b92d55d7310f17e3746457cd76ecdae5dbed20aee80276b61d30824b38093d13c3f4753b69925e819dac9471bcfd5d1c1733aa46c78dd68969d0350c24a0c7
-  data.tar.gz: 0bbec9e620ec3fa03151b8dc4d6223b8a1de5d6b18cb4731c96df73d1bd2a9fb25a862c4dc3cbe27093468376a61c90d32f6763ef95f88f9c2f78118a077934e
+  metadata.gz: 0de59f1a428c9be0cd4e1926a8f1d59f1cca46c8fbdc77248fe34ab21c755412c39db3bfabcaa86855be878e707cfdb61e2d74a983c7ae2625de50eed3b96184
+  data.tar.gz: 4e77dc58ce51dc7a8d9027cabdab9465b82b3e9abccce7bbfb3591f8fd12cd36dbd4f28953118ec41ec3bc9f64b0569045d3e191c362ba8dbdcb9decaa9312e6

data/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to this project will be documented in this file.
 
+
+## [0.4.0] - 2026-10-20
+
+### Changed
+
+- Moved agent-level configuration to RubyLLM agents.
+
+### Added
+
+#### Configuration
+
+- RubyLLM agent configuration DSL support on `ActionAI::Agent`: class methods `model`, `instructions`, `tools`, `tool_options`, `server_tools`, `thinking`, `citations`, `caching`, `compaction`, `provider_options`, `headers`, `schema`, `fallbacks`, `context`, `chat_model`, `inputs`, `temperature`, `max_output_tokens`, and `end_user` configure a private, internally managed `RubyLLM::Agent` subclass.
+  `chat` is built via that agent’s `.chat` instead of plain `RubyLLM.chat`.
+- Parameters set through `ActionAI::Parameterized` are forwarded as the agent’s runtime `inputs`.
+
+#### Schemas
+
+- Consider Active Record _stored attributes_ for schema inference.
+  The type is `string` because `ActiveRecord::Store` doesn’t provide type casting. The same is true for the attributes a model will get from a user-filled form, so the behavior is consistent. One should override attribute setters for type casting if needed.
+
+### Removed
+
+#### Configuration
+
+- `default`/`default_options=` class method and `default_params` class attribute.
+  Use the RubyLLM agent DSL (`model`, `instructions`, and so on) instead.
+
+
+## [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 +63,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

@@ -22,7 +22,7 @@ automatically at the end of the action unless you have already called it.
 This can be as simple as:
 
   class Generator < ApplicationAI
-    default model: "gpt-4o"
+    model "gpt-6.1-sol"
 
     def code(task, language)
       @task     = task
@@ -88,33 +88,163 @@ You can also chain multiple agent actions to compose a small workflow before rea
   WorkflowAgent.collect("release notes").refine(style: "bullet list").content
   # => collected release notes refined as bullet list
 
-== Setting defaults
+== Configuration
+
+Your agent class uses the full +RubyLLM::Agent+ configuration DSL
+directly. You never need to define or reference a +RubyLLM::Agent+
+subclass yourself; just call +model+, +instructions+, +tools+, +schema+, and
+the other +RubyLLM::Agent+ class macros right on your Action AI agent:
 
-It is possible to set default values that will be used in every method in your
-Action AI Agent class. To implement this functionality, you just call the public
-class method +default+ which you get for free from ActionAI::Agent.
-This method accepts a Hash as the parameter. You can use any options
-supported by +RubyLLM::Chat+, such as +:provider+ and +:model+.
-Finally, it is also possible to pass in a
-Proc that will get evaluated when it is needed.
+  class Generator < ApplicationAI
+    model "gpt-6.1-sol"
+    instructions "You are a concise support assistant."
+    tools SearchDocs, LookupAccount
 
-Note that every value you set with this method will get overwritten if you use the
-same key in your agent method.
+    def code(task, language)
+      @task     = task
+      @language = language
+    end
+  end
 
-Example:
+If you declare +inputs+, use ActionAI::Parameterized to supply them at call
+time; the parameters given to +with+ are forwarded as the agent's runtime
+inputs:
 
   class Generator < ApplicationAI
-    default model: proc { Current.user.preferred_model }
+    inputs :workspace
+
+    instructions { "You are helping #{workspace.name}" }
   end
 
-== Configuration
+  Generator.with(workspace:).code("Parse CSV", :ruby)
+
+Subclasses inherit their parent's RubyLLM agent configuration and can extend
+or override it, the same way +RubyLLM::Agent+ subclasses do:
 
-The Agent class has the full list of configuration options. Here's an example:
+  class ApplicationAI < ActionAI::Agent
+    model "gpt-6-luna", provider: :openai
+  end
+
+  class Generator < ApplicationAI
+    model { Current.user.preferred_model }
+  end
+
+The Agent class has a few settings unrelated to the RubyLLM agent DSL that are specified on the class level.
+Here's an example:
+
+  ActionAI::Agent.execute_later_queue_name = :ai_agents
+
+* +logger+ — the logger is used for generating information on prompt execution if available.
+  Can be set to +nil+ for no logging. Compatible with both Ruby's own +Logger+ and Log4r loggers.
+
+* +execution_job+ — The job class used with +later+. Agents can set this to use a
+  custom execution job. Defaults to +ActionAI::ExecutionJob+.
+
+* +execute_later_queue_name+ — The queue name used by +later+ with the default
+  +execution_job+. Agents can set this to use a custom queue name.
+
+== 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
 
-  ActionAI::Agent.default_options = {
-    provider: :openai,
-    model: "gpt-4o-mini"
-  }
+  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

data/lib/action_ai/agent.rb

@@ -4,6 +4,9 @@ require "ruby_llm"
 require "active_support/core_ext/string/inflections"
 require "active_support/core_ext/hash/except"
 require "active_support/core_ext/module/anonymous"
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/try"
+require "active_support/core_ext/object/with_options"
 require "memery"
 
 require "action_ai/log_subscriber"
@@ -26,12 +29,11 @@ module ActionAI
   # the prompt views, options on the AI model used such as the <tt>:model</tt> ID, and attachments.
   #
   #   class ApplicationAI < ActionAI::Agent
-  #     default model: 'gpt-4o-mini',
-  #             provider: :openai
+  #     model "gpt-6-luna", provider: :openai
   #   end
   #
   #   class Generator < ApplicationAI
-  #     default model: 'gpt-4o'
+  #     model "gpt-6.1-sol"
   #
   #     def code(task, language)
   #       @task     = task
@@ -155,33 +157,40 @@ module ActionAI
   #       end
   #     end
   #
-  # == Default \Hash
+  # == Configuration
   #
-  # Action AI provides some intelligent defaults for your AI interactions, these are usually specified in a
-  # default method inside the class definition:
+  # Action AI agents configure their model, instructions, tools, and other
+  # chat options using the +RubyLLM::Agent+ class DSL directly. You never
+  # need to define or reference a +RubyLLM::Agent+ subclass yourself; just
+  # call +model+, +instructions+, +tools+, +schema+, and the other
+  # +RubyLLM::Agent+ class macros right on your +ActionAI::Agent+ subclass:
   #
   #   class Generator < ApplicationAI
-  #     default model: 'gpt-4o'
+  #     model "gpt-6.1-sol"
+  #     instructions "You are a concise support assistant."
+  #     tools SearchDocs, LookupAccount
   #   end
   #
-  # You can pass in any config value that a +RubyLLM::Chat+ accepts.
+  # Under the hood, Action AI manages a private +RubyLLM::Agent+ subclass for you
+  # and builds +chat+ from it, so instructions, tools, schema, fallbacks, caching,
+  # and every other declaration are honored exactly as documented on
+  # <tt>RubyLLM::Agent</tt>. Any params set through ActionAI::Parameterized
+  # (<tt>Generator.with(...)</tt>) are forwarded as its runtime +inputs+.
   #
-  # Finally, Action AI also supports passing <tt>Proc</tt> and <tt>Lambda</tt> objects into the default hash,
-  # so you can define methods that evaluate as the message is being generated:
+  # Configuration is inherited the same way +RubyLLM::Agent+ subclasses inherit
+  # it, so a shared +ApplicationAI+ base class can declare a default +model+ and
+  # +instructions+ that every agent subclass then extends or overrides:
   #
-  #   class Generator < ApplicationAI
-  #     default model: -> { Current.user.preferred_model },
-  #             api_key: proc { Current.user.ai_api_key }
+  #   class ApplicationAI < ActionAI::Agent
+  #     model "gpt-6-luna", provider: :openai
   #   end
   #
-  # Note that the proc/lambda is evaluated right at the start of the prompt generation, so if you
-  # set something in the default hash using a proc, and then set the same thing inside of your
-  # agent method, it will get overwritten by the agent method.
-  #
-  # It is also possible to set these default options that will be used in all agents through
-  # the <tt>default_options=</tt> configuration in <tt>config/application.rb</tt>:
+  #   class Generator < ApplicationAI
+  #     model { Current.user.preferred_model }
+  #   end
   #
-  #    config.action_ai.default_options = { provider: :openai, model: "gpt-4o-mini" }
+  # ::rescue_from continues to handle agent-action level exceptions; use it as
+  # usual, there's no separate chat-level rescue mechanism to reach for.
   #
   # == \Callbacks
   #
@@ -265,9 +274,6 @@ module ActionAI
   # These options are specified on the class level, like
   # <tt>ActionAI::Agent.raise_execution_errors = true</tt>
   #
-  # * <tt>default_options</tt> - You can pass this in at a class level as well as within the class itself as
-  #   per the above section.
-  #
   # * <tt>logger</tt> - the logger is used for generating information on prompt execution if available.
   #   Can be set to +nil+ for no logging. Compatible with both Ruby's own +Logger+ and Log4r loggers.
   #
@@ -279,6 +285,7 @@ module ActionAI
   class Agent < AbstractController::Base
     include Callbacks
     include ImplicitInteraction
+    prepend StructuredOutput
     include QueuedExecution
     include Rescuable
     include Parameterized
@@ -303,11 +310,9 @@ module ActionAI
 
     helper ActionAI::PromptHelper
 
-    class_attribute :default_params, default: {
-      # none
-    }.freeze
-
     class << self
+      include Memery
+
       # Returns the name of the current agent. This method is also being used as a path for a view lookup.
       # If this is an anonymous agent, this method will return +anonymous+ instead.
       def agent_name
@@ -317,18 +322,18 @@ module ActionAI
       attr_writer :agent_name
       alias :controller_path :agent_name
 
-      # Allows to set defaults through app configuration:
-      #
-      #    config.action_ai.default_options = { provider: :openai }
-      def default(value = nil)
-        self.default_params = default_params.merge(value).freeze if value
-        default_params
+      # The private, per-agent-class +RubyLLM::Agent+ subclass,
+      # lazily created and configured via its own class macros
+      # (+model+, +instructions+, +tools+, +schema+, and so on).
+      memoize def agent_class
+        Class.new superclass.try(:agent_class) || RubyLLM::Agent
       end
-      alias :default_options= :default
 
     private
       def method_missing(method_name, ...)
-        if action_methods.include?(method_name.name)
+        if agent_class.respond_to? method_name # configuration
+          agent_class.public_send(method_name, ...)
+        elsif action_methods.include? method_name.name # actions
           Interaction.new(self, method_name, ...)
         else
           super
@@ -336,13 +341,22 @@ module ActionAI
       end
 
       def respond_to_missing?(method, include_all = false)
-        action_methods.include?(method.name) || super
+        agent_class.respond_to? method or
+            action_methods.include? method.name or
+                super
       end
     end
 
     attr_internal :message
 
-    memoize def chat = RubyLLM.chat(**apply_defaults)
+    memoize def agent = agent_class.new(**params
+      .slice(*agent_class.inputs)
+    )
+
+    with_options private: true do
+      delegate :agent_class, to: :class
+      delegate :chat,        to: :agent
+    end
 
     def process(method_name, *args) # :nodoc:
       payload = {
@@ -378,10 +392,10 @@ module ActionAI
     #
     # * +:with+ - Array of file paths or URLs to attach to the prompt.
     #
-    # You can set default model options using the ::default class method:
+    # You can set default model options using the ::model class method:
     #
     #  class Generator < ActionAI::Agent
-    #    default model: 'gpt-4o', provider: :openai
+    #    model "gpt-6.1-sol", provider: :openai
     #  end
     #
     # It will find a template in the view paths using by default the agent name and the
@@ -391,7 +405,7 @@ module ActionAI
     # For example:
     #
     #   class Generator < ActionAI::Agent
-    #     default model: 'gpt-4o'
+    #     model "gpt-6.1-sol"
     #
     #     def code(task, language)
     #       @task     = task
@@ -422,24 +436,6 @@ module ActionAI
         false
       end
 
-      def apply_defaults(config = {})
-        default_values = self.class.default.except(*config.keys).transform_values do |value|
-          compute_default(value)
-        end
-
-        config.reverse_merge(default_values)
-      end
-
-      def compute_default(value)
-        return value unless value.is_a?(Proc)
-
-        if value.arity == 1
-          instance_exec(self, &value)
-        else
-          instance_exec(&value)
-        end
-      end
-
       def use_attachments
         attachments.presence
           .tap { @attachments = nil } # reset

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