ruby_llm-agents 0.1.0

data/lib/generators/ruby_llm_agents/agent_generator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RubyLlmAgents
+  # Agent generator for creating new agents
+  #
+  # Usage:
+  #   rails generate ruby_llm_agents:agent SearchIntent query:required limit:10
+  #
+  # This will create:
+  #   - app/agents/search_intent_agent.rb
+  #
+  # Parameter syntax:
+  #   name           - Optional parameter
+  #   name:required  - Required parameter
+  #   name:default   - Optional with default value (e.g., limit:10)
+  #
+  class AgentGenerator < ::Rails::Generators::NamedBase
+    source_root File.expand_path("templates", __dir__)
+
+    argument :params, type: :array, default: [], banner: "param[:required|:default] param[:required|:default]"
+
+    class_option :model, type: :string, default: "gemini-2.0-flash",
+                 desc: "The LLM model to use"
+    class_option :temperature, type: :numeric, default: 0.0,
+                 desc: "The temperature setting (0.0-1.0)"
+    class_option :cache, type: :string, default: nil,
+                 desc: "Cache TTL (e.g., '1.hour', '30.minutes')"
+
+    def create_agent_file
+      template "agent.rb.tt", "app/agents/#{file_name}_agent.rb"
+    end
+
+    def show_usage
+      say ""
+      say "Agent #{class_name}Agent created!", :green
+      say ""
+      say "Usage:"
+      say "  #{class_name}Agent.call(#{usage_params})"
+      say "  #{class_name}Agent.call(#{usage_params}, dry_run: true)"
+      say ""
+    end
+
+    private
+
+    def parsed_params
+      @parsed_params ||= params.map do |param|
+        name, modifier = param.split(":")
+        ParsedParam.new(name, modifier)
+      end
+    end
+
+    def usage_params
+      parsed_params.map do |p|
+        if p.required?
+          "#{p.name}: value"
+        else
+          "#{p.name}: #{p.default || 'value'}"
+        end
+      end.join(", ")
+    end
+
+    # Helper class for parsing parameter definitions
+    class ParsedParam
+      attr_reader :name, :default
+
+      def initialize(name, modifier)
+        @name = name
+        @required = modifier == "required"
+        @default = @required ? nil : modifier
+      end
+
+      def required?
+        @required
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/install_generator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RubyLlmAgents
+  # Install generator for ruby_llm-agents
+  #
+  # Usage:
+  #   rails generate ruby_llm_agents:install
+  #
+  # This will:
+  #   - Create the migration for ruby_llm_agents_executions table
+  #   - Create the initializer at config/initializers/ruby_llm_agents.rb
+  #   - Create app/agents/application_agent.rb base class
+  #   - Optionally mount the dashboard engine in routes
+  #
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::ActiveRecord::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    class_option :skip_migration, type: :boolean, default: false,
+                 desc: "Skip generating the migration file"
+    class_option :skip_initializer, type: :boolean, default: false,
+                 desc: "Skip generating the initializer file"
+    class_option :mount_dashboard, type: :boolean, default: true,
+                 desc: "Mount the dashboard engine in routes"
+
+    def create_migration_file
+      return if options[:skip_migration]
+
+      migration_template(
+        "migration.rb.tt",
+        File.join(db_migrate_path, "create_ruby_llm_agents_executions.rb")
+      )
+    end
+
+    def create_initializer
+      return if options[:skip_initializer]
+
+      template "initializer.rb.tt", "config/initializers/ruby_llm_agents.rb"
+    end
+
+    def create_agents_directory
+      empty_directory "app/agents"
+    end
+
+    def create_application_agent
+      template "application_agent.rb.tt", "app/agents/application_agent.rb"
+    end
+
+    def mount_dashboard_engine
+      return unless options[:mount_dashboard]
+
+      route_content = 'mount RubyLLM::Agents::Engine => "/agents"'
+
+      if File.exist?(File.join(destination_root, "config/routes.rb"))
+        inject_into_file(
+          "config/routes.rb",
+          "  #{route_content}\n",
+          after: "Rails.application.routes.draw do\n"
+        )
+        say_status :route, route_content, :green
+      end
+    end
+
+    def show_post_install_message
+      say ""
+      say "RubyLLM::Agents has been installed!", :green
+      say ""
+      say "Next steps:"
+      say "  1. Run migrations: rails db:migrate"
+      say "  2. Generate an agent: rails generate ruby_llm_agents:agent MyAgent query:required"
+      say "  3. Access the dashboard at: /agents"
+      say ""
+    end
+
+    private
+
+    def migration_version
+      "[#{::ActiveRecord::VERSION::STRING.to_f}]"
+    end
+
+    def db_migrate_path
+      "db/migrate"
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/templates/add_prompts_migration.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class AddPromptsToRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    unless column_exists?(:ruby_llm_agents_executions, :system_prompt)
+      add_column :ruby_llm_agents_executions, :system_prompt, :text
+    end
+    unless column_exists?(:ruby_llm_agents_executions, :user_prompt)
+      add_column :ruby_llm_agents_executions, :user_prompt, :text
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Agent < ApplicationAgent
+  model "<%= options[:model] %>"
+  temperature <%= options[:temperature] %>
+  version "1.0"
+<% if options[:cache] -%>
+  cache <%= options[:cache] %>
+<% else -%>
+  # cache 1.hour  # Uncomment to enable caching
+<% end -%>
+
+<% parsed_params.each do |param| -%>
+  param :<%= param.name %><%= ", required: true" if param.required? %><%= ", default: #{param.default.inspect}" if param.default && !param.required? %>
+<% end -%>
+
+  private
+
+  def system_prompt
+    <<~PROMPT
+      You are a helpful assistant.
+      # Define your system instructions here
+    PROMPT
+  end
+
+  def user_prompt
+    # Build the prompt from parameters
+<% if parsed_params.any? -%>
+    <%= parsed_params.first.name %>
+<% else -%>
+    "Your prompt here"
+<% end -%>
+  end
+
+  # Uncomment to use structured output with RubyLLM::Schema
+  # def schema
+  #   @schema ||= RubyLLM::Schema.create do
+  #     string :result, description: "The result"
+  #   end
+  # end
+
+  # Uncomment to add custom metadata to execution logs
+  # def execution_metadata
+  #   { custom_field: value }
+  # end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# ApplicationAgent - Base class for all agents in this application
+#
+# All agents should inherit from this class to share common configuration.
+#
+# Example:
+#   class MyAgent < ApplicationAgent
+#     param :query, required: true
+#
+#     def user_prompt
+#       query
+#     end
+#   end
+#
+class ApplicationAgent < RubyLLM::Agents::Base
+  # Shared configuration for all agents
+  # Uncomment and modify as needed:
+  #
+  # model "gemini-2.0-flash"
+  # temperature 0.0
+end

data/lib/generators/ruby_llm_agents/templates/initializer.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Configuration for RubyLLM::Agents
+#
+# For more information, see: https://github.com/adham90/ruby_llm-agents
+
+RubyLLM::Agents.configure do |config|
+  # Default model for all agents (can be overridden per agent)
+  # config.default_model = "gemini-2.0-flash"
+
+  # Default temperature (0.0 = deterministic, 1.0 = creative)
+  # config.default_temperature = 0.0
+
+  # Default timeout in seconds
+  # config.default_timeout = 60
+
+  # Cache store for agent response caching (defaults to Rails.cache)
+  # config.cache_store = Rails.cache
+
+  # Async logging (set to false to log synchronously, useful for debugging)
+  # config.async_logging = true
+
+  # Retention period for execution records (used by cleanup tasks)
+  # config.retention_period = 30.days
+
+  # Anomaly detection thresholds (executions exceeding these are logged as warnings)
+  # config.anomaly_cost_threshold = 5.00        # dollars
+  # config.anomaly_duration_threshold = 10_000  # milliseconds
+
+  # Dashboard authentication
+  # Return true to allow access, false to deny
+  # config.dashboard_auth = ->(controller) { controller.current_user&.admin? }
+
+  # Parent controller for dashboard (for authentication/layout inheritance)
+  # config.dashboard_parent_controller = "ApplicationController"
+end

data/lib/generators/ruby_llm_agents/templates/migration.rb.tt

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class CreateRubyLlmAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :ruby_llm_agents_executions do |t|
+      # Agent identification
+      t.string :agent_type, null: false
+      t.string :agent_version, default: "1.0"
+
+      # Model configuration
+      t.string :model_id, null: false
+      t.string :model_provider
+      t.decimal :temperature, precision: 3, scale: 2
+
+      # Timing
+      t.datetime :started_at, null: false
+      t.datetime :completed_at
+      t.integer :duration_ms
+
+      # Status
+      t.string :status, default: "success", null: false
+
+      # Token usage
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.integer :total_tokens
+      t.integer :cached_tokens, default: 0
+      t.integer :cache_creation_tokens, default: 0
+
+      # Costs (in dollars, 6 decimal precision)
+      t.decimal :input_cost, precision: 12, scale: 6
+      t.decimal :output_cost, precision: 12, scale: 6
+      t.decimal :total_cost, precision: 12, scale: 6
+
+      # Data (JSONB for PostgreSQL, JSON for others)
+      t.jsonb :parameters, null: false, default: {}
+      t.jsonb :response, default: {}
+      t.jsonb :metadata, null: false, default: {}
+
+      # Error tracking
+      t.string :error_class
+      t.text :error_message
+
+      # Prompts (for history/changelog)
+      t.text :system_prompt
+      t.text :user_prompt
+
+      t.timestamps
+    end
+
+    # Indexes for common queries
+    add_index :ruby_llm_agents_executions, :agent_type
+    add_index :ruby_llm_agents_executions, :status
+    add_index :ruby_llm_agents_executions, :created_at
+    add_index :ruby_llm_agents_executions, [:agent_type, :created_at]
+    add_index :ruby_llm_agents_executions, [:agent_type, :status]
+    add_index :ruby_llm_agents_executions, [:agent_type, :agent_version]
+    add_index :ruby_llm_agents_executions, :duration_ms
+    add_index :ruby_llm_agents_executions, :total_cost
+
+    # GIN indexes for JSONB columns (PostgreSQL only)
+    # Uncomment if using PostgreSQL:
+    # add_index :ruby_llm_agents_executions, :parameters, using: :gin
+    # add_index :ruby_llm_agents_executions, :metadata, using: :gin
+  end
+end

data/lib/generators/ruby_llm_agents/upgrade_generator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RubyLlmAgents
+  # Upgrade generator for ruby_llm-agents
+  #
+  # Usage:
+  #   rails generate ruby_llm_agents:upgrade
+  #
+  # This will create any missing migrations for upgrading from older versions.
+  #
+  class UpgradeGenerator < ::Rails::Generators::Base
+    include ::ActiveRecord::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    def create_add_prompts_migration
+      # Check if columns already exist
+      if column_exists?(:ruby_llm_agents_executions, :system_prompt)
+        say_status :skip, "system_prompt column already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "add_prompts_migration.rb.tt",
+        File.join(db_migrate_path, "add_prompts_to_ruby_llm_agents_executions.rb")
+      )
+    end
+
+    def show_post_upgrade_message
+      say ""
+      say "RubyLLM::Agents upgrade migration created!", :green
+      say ""
+      say "Next steps:"
+      say "  1. Run migrations: rails db:migrate"
+      say ""
+    end
+
+    private
+
+    def migration_version
+      "[#{::ActiveRecord::VERSION::STRING.to_f}]"
+    end
+
+    def db_migrate_path
+      "db/migrate"
+    end
+
+    def column_exists?(table, column)
+      return false unless ActiveRecord::Base.connection.table_exists?(table)
+
+      ActiveRecord::Base.connection.column_exists?(table, column)
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/ruby_llm/agents/base.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+# RubyLLM::Agents::Base - Base class for LLM-powered agents
+#
+# == Creating an Agent
+#
+#   class SearchAgent < ApplicationAgent
+#     model "gemini-2.0-flash"
+#     temperature 0.0
+#     version "1.0"
+#     timeout 30
+#     cache 1.hour
+#
+#     param :query, required: true
+#     param :limit, default: 10
+#
+#     def system_prompt
+#       "You are a search assistant..."
+#     end
+#
+#     def user_prompt
+#       query
+#     end
+#
+#     def schema
+#       @schema ||= RubyLLM::Schema.create do
+#         string :result
+#       end
+#     end
+#   end
+#
+# == Calling an Agent
+#
+#   SearchAgent.call(query: "red dress")
+#   SearchAgent.call(query: "red dress", dry_run: true)    # Debug prompts
+#   SearchAgent.call(query: "red dress", skip_cache: true) # Bypass cache
+#
+# == Configuration DSL
+#
+#   model "gemini-2.0-flash"  # LLM model (default from config)
+#   temperature 0.0           # Randomness 0.0-1.0 (default from config)
+#   version "1.0"             # Version for cache invalidation
+#   timeout 30                # Seconds before timeout (default from config)
+#   cache 1.hour              # Enable caching with TTL (default: disabled)
+#
+# == Parameter DSL
+#
+#   param :name                     # Optional parameter
+#   param :query, required: true    # Required - raises ArgumentError if missing
+#   param :limit, default: 10       # Optional with default value
+#
+# == Template Methods (override in subclasses)
+#
+#   user_prompt   - Required. The prompt sent to the LLM.
+#   system_prompt - Optional. System instructions for the LLM.
+#   schema        - Optional. RubyLLM::Schema for structured output.
+#   process_response(response) - Optional. Post-process the LLM response.
+#   cache_key_data - Optional. Override to customize cache key generation.
+#
+module RubyLLM
+  module Agents
+    class Base
+      include Instrumentation
+
+      # Default constants (can be overridden by configuration)
+      VERSION     = "1.0".freeze
+      CACHE_TTL   = 1.hour
+
+      # ==========================================================================
+      # Class Methods (DSL)
+      # ==========================================================================
+
+      class << self
+        # Factory method - instantiates and calls the agent
+        def call(*args, **kwargs)
+          new(*args, **kwargs).call
+        end
+
+        # ------------------------------------------------------------------------
+        # Configuration DSL
+        # ------------------------------------------------------------------------
+
+        def model(value = nil)
+          @model = value if value
+          @model || inherited_or_default(:model, RubyLLM::Agents.configuration.default_model)
+        end
+
+        def temperature(value = nil)
+          @temperature = value if value
+          @temperature || inherited_or_default(:temperature, RubyLLM::Agents.configuration.default_temperature)
+        end
+
+        def version(value = nil)
+          @version = value if value
+          @version || inherited_or_default(:version, VERSION)
+        end
+
+        def timeout(value = nil)
+          @timeout = value if value
+          @timeout || inherited_or_default(:timeout, RubyLLM::Agents.configuration.default_timeout)
+        end
+
+        # ------------------------------------------------------------------------
+        # Parameter DSL
+        # ------------------------------------------------------------------------
+
+        def param(name, required: false, default: nil)
+          @params ||= {}
+          @params[name] = { required: required, default: default }
+          define_method(name) do
+            @options[name] || @options[name.to_s] || self.class.params.dig(name, :default)
+          end
+        end
+
+        def params
+          parent = superclass.respond_to?(:params) ? superclass.params : {}
+          parent.merge(@params || {})
+        end
+
+        # ------------------------------------------------------------------------
+        # Caching DSL
+        # ------------------------------------------------------------------------
+
+        def cache(ttl = CACHE_TTL)
+          @cache_enabled = true
+          @cache_ttl = ttl
+        end
+
+        def cache_enabled?
+          @cache_enabled || false
+        end
+
+        def cache_ttl
+          @cache_ttl || CACHE_TTL
+        end
+
+        private
+
+        def inherited_or_default(method, default)
+          superclass.respond_to?(method) ? superclass.send(method) : default
+        end
+      end
+
+      # ==========================================================================
+      # Instance Methods
+      # ==========================================================================
+
+      attr_reader :model, :temperature, :client
+
+      def initialize(model: self.class.model, temperature: self.class.temperature, **options)
+        @model = model
+        @temperature = temperature
+        @options = options
+        validate_required_params!
+        @client = build_client
+      end
+
+      # Main entry point
+      def call
+        return dry_run_response if @options[:dry_run]
+        return uncached_call if @options[:skip_cache] || !self.class.cache_enabled?
+
+        cache_store.fetch(cache_key, expires_in: self.class.cache_ttl) do
+          uncached_call
+        end
+      end
+
+      # --------------------------------------------------------------------------
+      # Template Methods (override in subclasses)
+      # --------------------------------------------------------------------------
+
+      def user_prompt
+        raise NotImplementedError, "#{self.class} must implement #user_prompt"
+      end
+
+      def system_prompt
+        nil
+      end
+
+      def schema
+        nil
+      end
+
+      def process_response(response)
+        content = response.content
+        return content unless content.is_a?(Hash)
+        content.transform_keys(&:to_sym)
+      end
+
+      # Debug mode - returns prompt info without API call
+      def dry_run_response
+        {
+          dry_run: true,
+          agent: self.class.name,
+          model: model,
+          temperature: temperature,
+          timeout: self.class.timeout,
+          system_prompt: system_prompt,
+          user_prompt: user_prompt,
+          schema: schema&.class&.name
+        }
+      end
+
+      # ==========================================================================
+      # Private Methods
+      # ==========================================================================
+
+      private
+
+      def uncached_call
+        instrument_execution do
+          Timeout.timeout(self.class.timeout) do
+            response = client.ask(user_prompt)
+            process_response(capture_response(response))
+          end
+        end
+      end
+
+      # --------------------------------------------------------------------------
+      # Caching
+      # --------------------------------------------------------------------------
+
+      def cache_store
+        RubyLLM::Agents.configuration.cache_store
+      end
+
+      def cache_key
+        ["ruby_llm_agent", self.class.name, self.class.version, cache_key_hash].join("/")
+      end
+
+      def cache_key_hash
+        Digest::SHA256.hexdigest(cache_key_data.to_json)
+      end
+
+      # Override to customize what's included in cache key
+      def cache_key_data
+        @options.except(:skip_cache, :dry_run)
+      end
+
+      # --------------------------------------------------------------------------
+      # Validation
+      # --------------------------------------------------------------------------
+
+      def validate_required_params!
+        required = self.class.params.select { |_, v| v[:required] }.keys
+        missing = required.reject { |p| @options.key?(p) || @options.key?(p.to_s) }
+        raise ArgumentError, "#{self.class} missing required params: #{missing.join(', ')}" if missing.any?
+      end
+
+      # --------------------------------------------------------------------------
+      # Client Building
+      # --------------------------------------------------------------------------
+
+      def build_client
+        client = RubyLLM.chat
+          .with_model(model)
+          .with_temperature(temperature)
+        client = client.with_instructions(system_prompt) if system_prompt
+        client = client.with_schema(schema) if schema
+        client
+      end
+
+      # Helper for subclasses that need conversation history
+      def build_client_with_messages(messages)
+        messages.reduce(build_client) do |client, message|
+          client.with_message(message[:role], message[:content])
+        end
+      end
+    end
+  end
+end