activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent.rb

@@ -1,42 +1,126 @@
-require "yaml"
+# frozen_string_literal: true
+
+
 require "abstract_controller"
-require "active_agent/configuration"
-require "active_agent/generation_provider"
 require "active_agent/version"
 require "active_agent/deprecator"
-require "active_agent/railtie" if defined?(Rails)
-require "active_agent/sanitizers"
 
+# Common Active Support usage in Action Agent
 require "active_support"
 require "active_support/rails"
 require "active_support/core_ext/class"
 require "active_support/core_ext/module/attr_internal"
 require "active_support/core_ext/string/inflections"
 require "active_support/lazy_load_hooks"
+
+# Module Level Extensions
+require "active_agent/configuration"
+require "active_agent/railtie" if defined?(Rails)
+
+# ActiveAgent is a framework for building AI agents with Rails-like conventions.
+#
+# It provides a structured approach to interacting with Large Language Models (LLMs)
+# by offering a familiar interface inspired by ActionMailer. ActiveAgent handles
+# prompt management, tool integration, streaming responses, and provider abstraction.
+#
+# = Core Concepts
+#
+# * **Agents**: Classes that inherit from {ActiveAgent::Base} and define prompts as methods
+# * **Prompts**: Methods that return {Generation} objects for LLM interactions
+# * **Tools**: Ruby methods that can be called by LLMs during generation
+# * **Providers**: Abstraction layer for different LLM services (OpenAI, Anthropic, etc.)
+# * **Streaming**: Real-time response handling via Server-Sent Events
+#
+# @example Creating a simple agent
+#   class GreetingAgent < ActiveAgent::Base
+#     generate_with :openai
+#
+#     def welcome(name:)
+#       @name = name
+#     end
+#   end
+#
+#   # app/views/greeting_agent/welcome.md.erb
+#   # Hello <%= @name %>! How can I help you today?
+#
+#   generation = GreetingAgent.welcome(name: "Alice")
+#   response = generation.generate_now
+#
+# @example Using tools
+#   class WeatherAgent < ActiveAgent::Base
+#     generate_with :anthropic
+#
+#     tool def get_weather(location:)
+#       # Call weather API
+#       { temperature: 72, condition: "sunny" }
+#     end
+#
+#     def forecast(location:)
+#       @location = location
+#     end
+#   end
+#
+# @example Streaming responses
+#   class ChatAgent < ActiveAgent::Base
+#     generate_with :openai
+#
+#     def chat(message:)
+#       @message = message
+#     end
+#   end
+#
+#   ChatAgent.chat(message: "Tell me a story").generate do |stream|
+#     stream.on_text_delta { |delta| print delta }
+#     stream.on_tool_call { |name, args| puts "Calling #{name}" }
+#   end
+#
+# @see ActiveAgent::Base
+# @see ActiveAgent::Configuration
+# @see https://github.com/quiltt/activeagent ActiveAgent on GitHub
 module ActiveAgent
-  include ActiveAgent::Sanitizers
   extend ActiveSupport::Autoload
 
+  # Eager autoload critical components.
+  #
+  # These components are loaded immediately when {eager_load!} is called,
+  # typically during Rails initialization in production environments.
   eager_autoload do
     autoload :Collector
   end
 
+  # Lazy autoload remaining components.
+  #
+  # These components are loaded on-demand when first referenced.
   autoload :Base
-  autoload :Callbacks
-  autoload :Streaming
+  autoload :Callbacks, "active_agent/concerns/callbacks"
+  autoload :Streaming, "active_agent/concerns/streaming"
   autoload :InlinePreviewInterceptor
-  autoload :PromptHelper
   autoload :Generation
-  autoload :GenerationProvider
-  autoload :QueuedGeneration
-  autoload :Parameterized
-  autoload :Preview
-  autoload :Previews, "active_agent/preview"
+  autoload :Queueing, "active_agent/concerns/queueing"
+  autoload :Parameterized, "active_agent/concerns/parameterized"
+  autoload :Preview, "active_agent/concerns/preview"
+  autoload :Previews, "active_agent/concerns/preview"
   autoload :GenerationJob
+  autoload :Observers, "active_agent/concerns/observers"
+  autoload :Provider, "active_agent/concerns/provider"
+  autoload :Rescue, "active_agent/concerns/rescue"
+  autoload :Tooling, "active_agent/concerns/tooling"
+  autoload :View, "active_agent/concerns/view"
 
   class << self
-    attr_accessor :config
-
+    # Eagerly loads all ActiveAgent components and descendant agent classes.
+    #
+    # This method is called during Rails initialization in production mode
+    # to load all code upfront, improving request performance and catching
+    # load-time errors early.
+    #
+    # @return [void]
+    #
+    # @example Manual eager loading
+    #   ActiveAgent.eager_load!
+    #
+    # @note In Rails applications, this is automatically called when
+    #   +config.eager_load+ is true (default in production).
     def eager_load!
       super
 
@@ -44,31 +128,23 @@ module ActiveAgent
         agent.eager_load! unless agent.abstract?
       end
     end
-
-    # @return [void]
-    def configure
-      yield self
-
-      sanitizers_reset!
-    end
-
-    # @return [void]
-    def load_configuration(file)
-      if File.exist?(file)
-        config_file = YAML.load(ERB.new(File.read(file)).result, aliases: true)
-        env = ENV["RAILS_ENV"] || ENV["ENV"] || "development"
-        @config = config_file[env] || config_file
-      else
-        @config = {}
-      end
-
-      sanitizers_reset!
-    end
   end
 end
 
+# Autoload MIME type support for content type handling.
+#
+# ActiveAgent uses ActionDispatch's MIME type system for handling
+# different content types in prompts and responses.
 autoload :Mime, "action_dispatch/http/mime_type"
 
+# Register markdown MIME type for template rendering, Not needed in Rails 8.1
+Mime::Type.register "text/markdown", :md, [], %w[md markdown] unless Mime::Type.lookup_by_extension(:md)
+
+# Configure ActionView integration when loaded.
+#
+# Sets up default formats and MIME type implementation for rendering
+# agent prompt templates. This ensures proper content type handling
+# for various template formats (.md.erb, .txt.erb, etc.).
 ActiveSupport.on_load(:action_view) do
   ActionView::Base.default_formats ||= Mime::SET.symbols
   ActionView::Template.mime_types_implementation = Mime

data/lib/generators/active_agent/agent/USAGE

@@ -0,0 +1,78 @@
+Description:
+    Generates a new agent and its views. Passes the agent name, either
+    CamelCased or under_scored, and an optional list of actions as arguments.
+
+    This generates an agent class in app/agents and invokes your template
+    engine and test framework generators. If no ApplicationAgent exists,
+    it will be created automatically.
+
+    By default, markdown format templates are created. You can specify text
+    format using the --format option. Optionally generate JSON schema files
+    for actions using the --json-schema flag, or use --json-object for
+    JSON object response format without schemas.
+
+Options:
+    --format=FORMAT       Specify format for templates (default: markdown)
+                          Can be: text, markdown
+                          Example: --format=text
+
+    --json-schema         Generate JSON schema files for each action
+                          Creates action_name.json files
+                          Sets response_format: :json_schema in agent methods
+
+    --json-object         Generate agent methods with JSON object response format
+                          Sets response_format: :json_object in agent methods
+                          Does not create schema files
+
+Examples:
+    `bin/rails generate active_agent:agent inventory search`
+
+    creates an inventory agent with markdown templates:
+        Agent:        app/agents/inventory_agent.rb
+        Instructions: app/views/inventory_agent/instructions.md
+        View:         app/views/inventory_agent/search.md.erb
+        Test:         test/docs/inventory_agent_test.rb
+
+    `bin/rails generate active_agent:agent inventory search --format=text`
+
+    creates an inventory agent with text templates:
+        Agent:        app/agents/inventory_agent.rb
+        Instructions: app/views/inventory_agent/instructions.text
+        View:         app/views/inventory_agent/search.text.erb
+        Test:         test/docs/inventory_agent_test.rb
+
+    `bin/rails generate active_agent:agent inventory search --json-schema`
+
+    creates an inventory agent with markdown templates and JSON schema:
+        Agent:        app/agents/inventory_agent.rb
+        Instructions: app/views/inventory_agent/instructions.md
+        View:         app/views/inventory_agent/search.md.erb
+        Schema:       app/views/inventory_agent/search.json
+        Test:         test/docs/inventory_agent_test.rb
+
+    `bin/rails generate active_agent:agent inventory search --json-object`
+
+    creates an inventory agent with JSON object response format:
+        Agent:        app/agents/inventory_agent.rb
+        Instructions: app/views/inventory_agent/instructions.md
+        View:         app/views/inventory_agent/search.md.erb
+        Test:         test/docs/inventory_agent_test.rb
+
+    `bin/rails generate active_agent:agent inventory search update report`
+
+    creates an inventory agent with multiple actions:
+        Agent:        app/agents/inventory_agent.rb
+        Instructions: app/views/inventory_agent/instructions.md
+        Views:        app/views/inventory_agent/search.md.erb
+                      app/views/inventory_agent/update.md.erb
+                      app/views/inventory_agent/report.md.erb
+        Test:         test/docs/inventory_agent_test.rb
+
+    `bin/rails generate active_agent:agent admin/user create --json-schema`
+
+    creates a namespaced admin/user agent with schema:
+        Agent:        app/agents/admin/user_agent.rb
+        Instructions: app/views/admin/user_agent/instructions.md
+        View:         app/views/admin/user_agent/create.md.erb
+        Schema:       app/views/admin/user_agent/create.json
+        Test:         test/docs/admin/user_agent_test.rb

data/lib/generators/active_agent/{agent_generator.rb → agent/agent_generator.rb}

@@ -3,9 +3,11 @@
 module ActiveAgent
   module Generators
     class AgentGenerator < ::Rails::Generators::NamedBase
-      source_root File.expand_path("templates", __dir__)
+      source_root File.expand_path("../templates", __dir__)
       argument :actions, type: :array, default: [], banner: "method method"
-      class_option :formats, type: :array, default: [ "text" ], desc: "Specify formats to generate (text, html, json)"
+      class_option :format, type: :string, default: "markdown", desc: "Specify format for templates (text or markdown)"
+      class_option :json_schema, type: :boolean, default: false, desc: "Generate JSON schema files for actions"
+      class_option :json_object, type: :boolean, default: false, desc: "Generate actions with JSON object response format"
 
       check_class_collision suffix: "Agent"
 
@@ -31,8 +33,16 @@ module ActiveAgent
 
       private
 
-      def formats
-        options[:formats].map(&:to_sym)
+      def format
+        options[:format].to_sym
+      end
+
+      def json_schema?
+        options[:json_schema]
+      end
+
+      def json_object?
+        options[:json_object]
       end
 
       def file_name # :doc:

data/lib/generators/active_agent/install/USAGE

@@ -0,0 +1,25 @@
+Description:
+    Sets up ActiveAgent in your Rails application by creating the necessary
+    configuration files and application agent class.
+
+    This generator creates:
+    - Configuration file (config/active_agent.yml) unless --skip-config is used
+    - Application agent base class (app/agents/application_agent.rb)
+
+Options:
+    --skip-config         Skip the creation of config/active_agent.yml
+
+Examples:
+    `bin/rails generate active_agent:install`
+
+    creates the basic ActiveAgent setup:
+        Config:     config/active_agent.yml
+        Base Agent: app/agents/application_agent.rb
+
+    `bin/rails generate active_agent:install --skip-config`
+
+    creates ActiveAgent setup without configuration file:
+        Base Agent: app/agents/application_agent.rb
+
+    After running this generator, you can create individual agents with:
+    `bin/rails generate active_agent:agent AGENT_NAME ACTION_NAME`

data/lib/generators/active_agent/{install_generator.rb → install/install_generator.rb}

@@ -4,20 +4,8 @@ module ActiveAgent
   module Generators
     class InstallGenerator < ::Rails::Generators::Base
       class_option :skip_config, type: :boolean, default: false, desc: "Skip configuration file generation"
-      class_option :formats, type: :array, default: [ "text" ], desc: "Specify formats to generate (text, html, json)"
 
-      def initialize(*args, **kwargs)
-        super(*args, **kwargs)
-
-        # We must duplicate due to immutable hash
-        dup_options = options.dup
-        @options = dup_options.merge(template_engine: :erb)
-      end
-
-      def self.usage_path
-        @usage_path ||= File.expand_path("../USAGE", __dir__)
-      end
-      source_root File.expand_path("templates", __dir__)
+      source_root File.expand_path("../templates", __dir__)
 
       def create_configuration
         template "active_agent.yml", "config/active_agent.yml" unless options[:skip_config]
@@ -31,14 +19,8 @@ module ActiveAgent
         end
       end
 
-      hook_for :template_engine
-
       private
 
-      def formats
-        options[:formats].map(&:to_sym)
-      end
-
       def application_agent_file_name
         "app/agents/application_agent.rb"
       end

data/lib/generators/active_agent/templates/agent.rb.tt

@@ -5,9 +5,13 @@ class <%= class_name %>Agent < ApplicationAgent
 
 <% end -%>
   def <%= action %>
-    @message = "Cats go.."
-
-    prompt message: @message
+<% if json_schema? -%>
+    prompt(params[:message], response_format: :json_schema)
+<% elsif json_object? -%>
+    prompt(params[:message], response_format: :json_object)
+<% else -%>
+    prompt(params[:message])
+<% end -%>
   end
 <% end -%>
 end

data/lib/generators/active_agent/templates/application_agent.rb.tt

@@ -1,7 +1,5 @@
 <% module_namespacing do -%>
 class ApplicationAgent < ActiveAgent::Base
-  layout "agent"
-
   generate_with :openai, model: "gpt-4o-mini", instructions: "You are a helpful assistant."
 end
 <% end %>

data/lib/generators/erb/agent_generator.rb

@@ -7,7 +7,9 @@ module Erb # :nodoc:
     class AgentGenerator < Base # :nodoc:
       source_root File.expand_path("templates", __dir__)
       argument :actions, type: :array, default: [], banner: "method method"
-      class_option :formats, type: :array, default: [ "text" ], desc: "Specify formats to generate (text, html, json)"
+      class_option :format, type: :string, default: "markdown", desc: "Specify format for templates (text or markdown)"
+      class_option :json_schema, type: :boolean, default: false, desc: "Generate JSON schema files for actions"
+      class_option :json_object, type: :boolean, default: false, desc: "Generate actions with JSON object response format"
 
       def initialize(*args, **kwargs)
         super(*args, **kwargs)
@@ -18,32 +20,45 @@ module Erb # :nodoc:
       end
 
       def copy_view_files
-        view_base_path = File.join("app/views", class_path, file_name + "_agent")
+        view_base_path = File.join("app/views/agents", class_path, file_name)
         empty_directory view_base_path
 
-        if behavior == :invoke
-          formats.each do |format|
-            layout_path = File.join("app/views/layouts", class_path, filename_with_extensions("agent", format))
-            template filename_with_extensions(:layout, format), layout_path unless File.exist?(layout_path)
-          end
-        end
-
-        instructions_path = File.join(view_base_path, "instructions.text.erb")
-        template "instructions.text.erb.tt", instructions_path
+        # Create instructions file with the specified format (no .erb extension)
+        file_extension = format == "markdown" ? "md" : format
+        instructions_file = "instructions.#{file_extension}"
+        instructions_path = File.join(view_base_path, instructions_file)
+        template "instructions.#{file_extension}.tt", instructions_path
 
+        # Create action view files
         actions.each do |action|
           @action = action
 
-          formats.each do |format|
-            @path = File.join(view_base_path, filename_with_extensions(action, format))
-            template filename_with_extensions(:view, format), @path
+          # Create message file in specified format
+          action_file = "#{action}.#{file_extension}.erb"
+          action_path = File.join(view_base_path, action_file)
+          template "message.#{file_extension}.erb.tt", action_path
+
+          # Create schema file if requested
+          if json_schema?
+            schema_file = "#{action}.json"
+            schema_path = File.join(view_base_path, schema_file)
+            template "schema.json.tt", schema_path
           end
         end
       end
 
       private
-      def formats
-        options[:formats].map(&:to_sym)
+
+      def format
+        options[:format]
+      end
+
+      def json_schema?
+        options[:json_schema]
+      end
+
+      def json_object?
+        options[:json_object]
       end
 
       def file_name

data/lib/generators/erb/templates/instructions.md.erb.tt

@@ -0,0 +1,3 @@
+# Instructions
+
+Add your agent instructions here in markdown format.

data/lib/generators/erb/templates/instructions.md.tt

@@ -0,0 +1,3 @@
+# Instructions
+
+Add your agent instructions here in markdown format.

data/lib/generators/erb/templates/instructions.text.tt

@@ -0,0 +1 @@
+Instructions for an AI agent

data/lib/generators/erb/templates/message.md.erb.tt

@@ -0,0 +1,5 @@
+# <%= class_name %>#<%= @action %>
+
+Add your message template here. You can use ERB to access instance variables and params.
+
+Example: <%%= @message %>

data/lib/generators/erb/templates/schema.json.tt

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "properties": {
+    "example_property": {
+      "type": "string",
+      "description": "Add your property description here"
+    }
+  },
+  "required": ["example_property"]
+}

data/lib/generators/test_unit/agent_generator.rb

@@ -17,7 +17,7 @@ module TestUnit # :nodoc:
       end
 
       def create_preview_files
-        template "preview.rb", File.join("test/agents/previews", class_path, "#{file_name}_agent_preview.rb")
+        template "preview.rb", File.join("test/docs/previews", class_path, "#{file_name}_agent_preview.rb")
       end
 
       private

data/lib/generators/test_unit/templates/functional_test.rb.tt

@@ -7,8 +7,10 @@ class <%= class_name %>AgentTest < ActiveAgent::TestCase
 
 <% end -%>
   test "<%= action %>" do
-    agent = <%= class_name %>Agent.<%= action %>
-    assert_equal <%= action.to_s.humanize.inspect %>, agent.prompt_context
+    generation = <%= class_name %>Agent.<%= action %>
+    assert_not_nil generation
+    # Test the generation by calling generate_now if needed
+    # response = generation.generate_now
   end
 <% end -%>
 <% if actions.blank? -%>