action_ai 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 626b0d7eb4998d7c208dc99eb8e60932a3006988176bbd784935f1e00437b485
-  data.tar.gz: 97512e0c8fd015af6235d61b31ed36e7030702ddaf4b436b18b462b39013bd55
+  metadata.gz: 3fa6d979d2013779ecfe3932a2c1bb04158dd99072ef5eb4b802f2ece910b34d
+  data.tar.gz: 46cb4d1ad9cca9f63c7af8d575abe3ad23fef1359d2f5d445617662e071b1ef6
 SHA512:
-  metadata.gz: 5721c21b4234b75cc9afce08eef6e5df89b4cb3364b75df8bbc3735c9ed3735d19fe6186d1893b678e5bfb9cddcbe15511909babd0ab7851f7663fd2c4fb1011
-  data.tar.gz: 025dec0b60c2b398450fe31174789df35689bef9a48a5c77627619c9df3c6fd2de62b153c968430a2135b0ca2cc9ee73e29049e502e5b34acbbd1217ba523fa4
+  metadata.gz: 0de59f1a428c9be0cd4e1926a8f1d59f1cca46c8fbdc77248fe34ab21c755412c39db3bfabcaa86855be878e707cfdb61e2d74a983c7ae2625de50eed3b96184
+  data.tar.gz: 4e77dc58ce51dc7a8d9027cabdab9465b82b3e9abccce7bbfb3591f8fd12cd36dbd4f28953118ec41ec3bc9f64b0569045d3e191c362ba8dbdcb9decaa9312e6

data/CHANGELOG.md

@@ -3,6 +3,33 @@
 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

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,34 +88,60 @@ 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:
+
+  class Generator < ApplicationAI
+    model "gpt-6.1-sol"
+    instructions "You are a concise support assistant."
+    tools SearchDocs, LookupAccount
+
+    def code(task, language)
+      @task     = task
+      @language = language
+    end
+  end
+
+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:
 
-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
+    inputs :workspace
+
+    instructions { "You are helping #{workspace.name}" }
+  end
 
-Note that every value you set with this method will get overwritten if you use the
-same key in your agent method.
+  Generator.with(workspace:).code("Parse CSV", :ruby)
 
-Example:
+Subclasses inherit their parent's RubyLLM agent configuration and can extend
+or override it, the same way +RubyLLM::Agent+ subclasses do:
+
+  class ApplicationAI < ActionAI::Agent
+    model "gpt-6-luna", provider: :openai
+  end
 
   class Generator < ApplicationAI
-    default model: proc { Current.user.preferred_model }
+    model { Current.user.preferred_model }
   end
 
-== Configuration
+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
 
-The Agent class has the full list of configuration options. Here's an example:
+* +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.
 
-  ActionAI::Agent.default_options = {
-    provider: :openai,
-    model: "gpt-4o-mini"
-  }
+* +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)
 

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.
   #
@@ -304,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
@@ -318,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
@@ -337,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 = {
@@ -379,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
@@ -392,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
@@ -423,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_record.rb

@@ -35,6 +35,20 @@ module ActionAI
               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

data/lib/action_ai/model_schema.rb

@@ -144,7 +144,7 @@ module ActionAI
       ].compact.presence
           &.map(&:to_a)
           &.inject(&:&)
-          &.then&.select(&:many?)&.first
+          &.then&.detect(&:many?)
 
       def attribute_const(name) = [
         *(yield if block_given?)

data/lib/action_ai/version.rb

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

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 -%>
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_ai
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
   - Alexander Senko
@@ -182,8 +182,8 @@ 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.3.0/CHANGELOG.md"
-  source_code_uri: "https://github.com/Alexander-Senko/action_ai/tree/v0.3.0"
+  changelog_uri: "https://github.com/Alexander-Senko/action_ai/blob/v0.4.0/CHANGELOG.md"
+  source_code_uri: "https://github.com/Alexander-Senko/action_ai/tree/v0.4.0"
   rubygems_mfa_required: "true"
 rdoc_options: []
 require_paths: