ruby_llm-agents 0.2.4 → 0.3.1

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Migration to add finish_reason column to executions
+#
+# This column tracks why the LLM stopped generating:
+# - stop: Natural end of response
+# - length: Hit max_tokens limit
+# - content_filter: Blocked by safety filter
+# - tool_calls: Model wants to call a tool
+# - other: Unknown reason
+#
+# Note: streaming and time_to_first_token_ms are added by add_streaming migration
+#
+# Run with: rails db:migrate
+class AddFinishReasonToRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :ruby_llm_agents_executions, :finish_reason, :string
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Migration to add routing and retry tracking columns to executions
+#
+# These columns help understand why fallbacks happen and which errors
+# are retryable for reliability analysis.
+#
+# Run with: rails db:migrate
+class AddRoutingToRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Fallback tracking - why did we switch models?
+    # Values: price_limit, quality_fail, rate_limit, timeout, safety, other
+    add_column :ruby_llm_agents_executions, :fallback_reason, :string
+
+    # Error classification
+    add_column :ruby_llm_agents_executions, :retryable, :boolean
+    add_column :ruby_llm_agents_executions, :rate_limited, :boolean
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddStreamingToRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :ruby_llm_agents_executions, :streaming, :boolean, default: false
+    add_column :ruby_llm_agents_executions, :time_to_first_token_ms, :integer
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Migration to add distributed tracing columns to executions
+#
+# These columns enable linking executions across services and debugging
+# production issues by correlating agent calls with web requests.
+#
+# Run with: rails db:migrate
+class AddTracingToRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Request correlation - links to the originating HTTP request
+    add_column :ruby_llm_agents_executions, :request_id, :string
+
+    # OpenTelemetry tracing - for distributed tracing
+    add_column :ruby_llm_agents_executions, :trace_id, :string
+    add_column :ruby_llm_agents_executions, :span_id, :string
+
+    # Execution hierarchy - for nested agent calls
+    add_column :ruby_llm_agents_executions, :parent_execution_id, :bigint
+    add_column :ruby_llm_agents_executions, :root_execution_id, :bigint
+
+    # Indexes for common lookups
+    add_index :ruby_llm_agents_executions, :request_id
+    add_index :ruby_llm_agents_executions, :trace_id
+    add_index :ruby_llm_agents_executions, :parent_execution_id
+    add_index :ruby_llm_agents_executions, :root_execution_id
+
+    # Foreign keys for execution hierarchy
+    add_foreign_key :ruby_llm_agents_executions, :ruby_llm_agents_executions,
+                    column: :parent_execution_id, on_delete: :nullify
+    add_foreign_key :ruby_llm_agents_executions, :ruby_llm_agents_executions,
+                    column: :root_execution_id, on_delete: :nullify
+  end
+end

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

@@ -1,21 +1,63 @@
 # frozen_string_literal: true
 
 class <%= class_name %>Agent < ApplicationAgent
+  # ============================================
+  # Model Configuration
+  # ============================================
+
   model "<%= options[:model] %>"
   temperature <%= options[:temperature] %>
   version "1.0"
+  # timeout 30  # Per-request timeout in seconds (default: 60)
+
+  # ============================================
+  # Caching
+  # ============================================
+
 <% if options[:cache] -%>
   cache <%= options[:cache] %>
 <% else -%>
-  # cache 1.hour  # Uncomment to enable caching
+  # cache 1.hour  # Enable response caching with TTL
 <% end -%>
 
+  # ============================================
+  # Reliability (Retries & Fallbacks)
+  # ============================================
+
+  # Automatic retries with exponential backoff
+  # - max: Number of retry attempts
+  # - backoff: :constant or :exponential
+  # - base: Base delay in seconds
+  # - max_delay: Maximum delay between retries
+  # - on: Additional error classes to retry on
+  # retries max: 2, backoff: :exponential, base: 0.4, max_delay: 3.0
+
+  # Fallback models (tried in order when primary model fails)
+  # fallback_models ["gpt-4o-mini", "claude-3-haiku"]
+
+  # Total timeout across all retry/fallback attempts
+  # total_timeout 30
+
+  # Circuit breaker (prevents repeated calls to failing models)
+  # - errors: Number of errors to trigger open state
+  # - within: Rolling window in seconds
+  # - cooldown: Time to wait before allowing requests again
+  # circuit_breaker errors: 5, within: 60, cooldown: 300
+
+  # ============================================
+  # Parameters
+  # ============================================
+
 <% parsed_params.each do |param| -%>
   param :<%= param.name %><%= ", required: true" if param.required? %><%= ", default: #{param.default.inspect}" if param.default && !param.required? %>
 <% end -%>
 
   private
 
+  # ============================================
+  # Prompts (required)
+  # ============================================
+
   def system_prompt
     <<~PROMPT
       You are a helpful assistant.
@@ -32,15 +74,35 @@ class <%= class_name %>Agent < ApplicationAgent
 <% end -%>
   end
 
-  # Uncomment to use structured output with RubyLLM::Schema
+  # ============================================
+  # Optional Overrides
+  # ============================================
+
+  # Structured output schema (returns parsed hash instead of raw text)
   # def schema
   #   @schema ||= RubyLLM::Schema.create do
   #     string :result, description: "The result"
+  #     integer :confidence, description: "Confidence score 1-100"
+  #     array :tags, description: "Relevant tags" do
+  #       string
+  #     end
   #   end
   # end
 
-  # Uncomment to add custom metadata to execution logs
+  # Custom response processing (default: symbolize hash keys)
+  # def process_response(response)
+  #   content = response.content
+  #   # Transform or validate the response
+  #   content
+  # end
+
+  # Custom metadata to include in execution logs
   # def execution_metadata
-  #   { custom_field: value }
+  #   { custom_field: "value", request_id: params[:request_id] }
+  # end
+
+  # Custom cache key data (default: all params except skip_cache, dry_run)
+  # def cache_key_data
+  #   { query: params[:query], locale: I18n.locale }
   # end
 end

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

@@ -2,7 +2,8 @@
 
 # ApplicationAgent - Base class for all agents in this application
 #
-# All agents should inherit from this class to share common configuration.
+# All agents inherit from this class. Configure shared settings here
+# that apply to all agents, or override them per-agent as needed.
 #
 # Example:
 #   class MyAgent < ApplicationAgent
@@ -13,10 +14,56 @@
 #     end
 #   end
 #
+# Usage:
+#   MyAgent.call(query: "hello")
+#   MyAgent.call(query: "hello", dry_run: true)    # Debug mode
+#   MyAgent.call(query: "hello", skip_cache: true) # Bypass cache
+#
 class ApplicationAgent < RubyLLM::Agents::Base
-  # Shared configuration for all agents
-  # Uncomment and modify as needed:
-  #
-  # model "gemini-2.0-flash"
-  # temperature 0.0
+  # ============================================
+  # Shared Model Configuration
+  # ============================================
+  # These settings are inherited by all agents
+
+  # model "gemini-2.0-flash"   # Default model for all agents
+  # temperature 0.0            # Default temperature (0.0 = deterministic)
+  # timeout 60                 # Default timeout in seconds
+
+  # ============================================
+  # Shared Caching
+  # ============================================
+
+  # cache 1.hour  # Enable caching for all agents (override per-agent if needed)
+
+  # ============================================
+  # Shared Reliability Settings
+  # ============================================
+  # Configure once here, all agents inherit these settings
+
+  # Automatic retries for all agents
+  # retries max: 2, backoff: :exponential, base: 0.4, max_delay: 3.0
+
+  # Shared fallback models
+  # fallback_models ["gpt-4o-mini", "claude-3-haiku"]
+
+  # Total timeout across retries/fallbacks
+  # total_timeout 30
+
+  # Circuit breaker (per agent-model pair)
+  # circuit_breaker errors: 5, within: 60, cooldown: 300
+
+  # ============================================
+  # Shared Helper Methods
+  # ============================================
+  # Define methods here that can be used by all agents
+
+  # Example: Common system prompt prefix
+  # def system_prompt_prefix
+  #   "You are an AI assistant for #{Rails.application.class.module_parent_name}."
+  # end
+
+  # Example: Common metadata
+  # def execution_metadata
+  #   { app_version: Rails.application.config.version }
+  # end
 end

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

@@ -5,37 +5,172 @@
 # 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)
+  # ============================================
+  # Model Defaults
+  # ============================================
+
+  # Default LLM model for all agents (can be overridden per agent with `model "model-name"`)
   # config.default_model = "gemini-2.0-flash"
 
-  # Default temperature (0.0 = deterministic, 1.0 = creative)
+  # Default temperature (0.0 = deterministic, 2.0 = creative)
   # config.default_temperature = 0.0
 
-  # Default timeout in seconds
+  # Default timeout in seconds for each LLM request
   # config.default_timeout = 60
 
+  # Enable streaming by default for all agents
+  # When enabled, agents stream responses and track time-to-first-token
+  # config.default_streaming = false
+
+  # ============================================
+  # Caching
+  # ============================================
+
   # Cache store for agent response caching (defaults to Rails.cache)
   # config.cache_store = Rails.cache
+  # config.cache_store = ActiveSupport::Cache::MemoryStore.new
 
-  # Async logging (set to false to log synchronously, useful for debugging)
+  # ============================================
+  # Execution Logging
+  # ============================================
+
+  # Async logging via background job (recommended for production)
+  # Set to false to log synchronously (useful for debugging)
   # config.async_logging = true
 
+  # Number of retry attempts for the async logging job on failure
+  # config.job_retry_attempts = 3
+
   # Retention period for execution records (used by cleanup tasks)
   # config.retention_period = 30.days
 
-  # Anomaly detection thresholds (executions exceeding these are logged as warnings)
+  # ============================================
+  # Anomaly Detection
+  # ============================================
+
+  # Executions exceeding these thresholds are logged as warnings
   # config.anomaly_cost_threshold = 5.00        # dollars
   # config.anomaly_duration_threshold = 10_000  # milliseconds
 
-  # HTTP Basic Auth (simple username/password protection)
+  # ============================================
+  # Dashboard Authentication
+  # ============================================
+
+  # Option 1: HTTP Basic Auth (simple username/password protection)
+  # Both username and password must be set to enable Basic Auth
   # config.basic_auth_username = "admin"
   # config.basic_auth_password = Rails.application.credentials.agents_password
 
-  # Dashboard authentication (advanced - custom logic)
+  # Option 2: Custom authentication (advanced)
   # Return true to allow access, false to deny
-  # Note: If basic_auth_username/password are set, they take precedence
+  # Note: If basic_auth is set, it takes precedence over dashboard_auth
   # config.dashboard_auth = ->(controller) { controller.current_user&.admin? }
 
   # Parent controller for dashboard (for authentication/layout inheritance)
   # config.dashboard_parent_controller = "ApplicationController"
+  # config.dashboard_parent_controller = "AdminController"
+
+  # ============================================
+  # Dashboard Display
+  # ============================================
+
+  # Number of records per page in dashboard listings
+  # config.per_page = 25
+
+  # Number of recent executions shown on the dashboard home
+  # config.recent_executions_limit = 10
+
+  # ============================================
+  # Reliability Defaults
+  # ============================================
+  # These defaults apply to all agents unless overridden per-agent
+
+  # Default retry configuration
+  # - max: Maximum retry attempts (0 = disabled)
+  # - backoff: Strategy (:constant or :exponential)
+  # - base: Base delay in seconds
+  # - max_delay: Maximum delay between retries
+  # - on: Additional error classes to retry on (extends defaults)
+  # config.default_retries = {
+  #   max: 2,
+  #   backoff: :exponential,
+  #   base: 0.4,
+  #   max_delay: 3.0,
+  #   on: []
+  # }
+
+  # Default fallback models (tried in order when primary model fails)
+  # config.default_fallback_models = ["gpt-4o-mini", "claude-3-haiku"]
+
+  # Default total timeout across all retry/fallback attempts (nil = no limit)
+  # config.default_total_timeout = 30
+
+  # ============================================
+  # Governance - Budget Tracking
+  # ============================================
+
+  # Budget limits for cost governance
+  # - global_daily/global_monthly: Limits across all agents
+  # - per_agent_daily/per_agent_monthly: Per-agent limits (Hash of agent name => limit)
+  # - enforcement: :none (disabled), :soft (warn only), :hard (block requests)
+  # config.budgets = {
+  #   global_daily: 25.0,
+  #   global_monthly: 500.0,
+  #   per_agent_daily: {
+  #     "ContentGeneratorAgent" => 10.0,
+  #     "SummaryAgent" => 5.0
+  #   },
+  #   per_agent_monthly: {
+  #     "ContentGeneratorAgent" => 200.0
+  #   },
+  #   enforcement: :soft
+  # }
+
+  # ============================================
+  # Governance - Alerts
+  # ============================================
+
+  # Alert notifications for important events
+  # - slack_webhook_url: Slack incoming webhook URL
+  # - webhook_url: Generic webhook URL (receives JSON POST)
+  # - on_events: Events to trigger alerts
+  #   - :budget_soft_cap - Soft budget limit reached
+  #   - :budget_hard_cap - Hard budget limit exceeded
+  #   - :breaker_open - Circuit breaker opened
+  #   - :agent_anomaly - Cost/duration anomaly detected
+  # - custom: Lambda for custom handling
+  # config.alerts = {
+  #   slack_webhook_url: ENV["SLACK_AGENTS_WEBHOOK"],
+  #   webhook_url: ENV["AGENTS_ALERT_WEBHOOK"],
+  #   on_events: [:budget_soft_cap, :budget_hard_cap, :breaker_open],
+  #   custom: ->(event, payload) {
+  #     Rails.logger.info("[AgentAlert] #{event}: #{payload}")
+  #   }
+  # }
+
+  # ============================================
+  # Governance - Data Handling
+  # ============================================
+
+  # Whether to persist prompts in execution records
+  # Set to false to reduce storage or for privacy compliance
+  # config.persist_prompts = true
+
+  # Whether to persist LLM responses in execution records
+  # config.persist_responses = true
+
+  # Redaction configuration for PII and sensitive data
+  # - fields: Parameter names to redact (extends defaults: password, token, api_key, secret, etc.)
+  # - patterns: Regex patterns to match and redact in string values
+  # - placeholder: String to replace redacted values with
+  # - max_value_length: Truncate values longer than this (nil = no limit)
+  # config.redaction = {
+  #   fields: %w[ssn credit_card phone_number email],
+  #   patterns: [
+  #     /\b\d{3}-\d{2}-\d{4}\b/,           # SSN
+  #     /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/  # Credit card
+  #   ],
+  #   placeholder: "[REDACTED]",
+  #   max_value_length: 5000
+  # }
 end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class CreateRubyLlmAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+class CreateRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :ruby_llm_agents_executions do |t|
       # Agent identification
@@ -17,6 +17,28 @@ class CreateRubyLlmAgentsExecutions < ActiveRecord::Migration<%= migration_versi
       t.datetime :completed_at
       t.integer :duration_ms
 
+      # Streaming and finish
+      t.boolean :streaming, default: false
+      t.integer :time_to_first_token_ms
+      t.string :finish_reason
+
+      # Distributed tracing
+      t.string :request_id
+      t.string :trace_id
+      t.string :span_id
+      t.bigint :parent_execution_id
+      t.bigint :root_execution_id
+
+      # Routing and retries
+      t.string :fallback_reason
+      t.boolean :retryable
+      t.boolean :rate_limited
+
+      # Caching
+      t.boolean :cache_hit, default: false
+      t.string :response_cache_key
+      t.datetime :cached_at
+
       # Status
       t.string :status, default: "success", null: false
 
@@ -58,6 +80,21 @@ class CreateRubyLlmAgentsExecutions < ActiveRecord::Migration<%= migration_versi
     add_index :ruby_llm_agents_executions, :duration_ms
     add_index :ruby_llm_agents_executions, :total_cost
 
+    # Tracing indexes
+    add_index :ruby_llm_agents_executions, :request_id
+    add_index :ruby_llm_agents_executions, :trace_id
+    add_index :ruby_llm_agents_executions, :parent_execution_id
+    add_index :ruby_llm_agents_executions, :root_execution_id
+
+    # Caching index
+    add_index :ruby_llm_agents_executions, :response_cache_key
+
+    # Foreign keys for execution hierarchy
+    add_foreign_key :ruby_llm_agents_executions, :ruby_llm_agents_executions,
+                    column: :parent_execution_id, on_delete: :nullify
+    add_foreign_key :ruby_llm_agents_executions, :ruby_llm_agents_executions,
+                    column: :root_execution_id, on_delete: :nullify
+
     # GIN indexes for JSONB columns (PostgreSQL only)
     # Uncomment if using PostgreSQL:
     # add_index :ruby_llm_agents_executions, :parameters, using: :gin

data/lib/generators/ruby_llm_agents/upgrade_generator.rb

@@ -29,6 +29,84 @@ module RubyLlmAgents
       )
     end
 
+    def create_add_attempts_migration
+      # Check if columns already exist
+      if column_exists?(:ruby_llm_agents_executions, :attempts)
+        say_status :skip, "attempts column already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "add_attempts_migration.rb.tt",
+        File.join(db_migrate_path, "add_attempts_to_ruby_llm_agents_executions.rb")
+      )
+    end
+
+    def create_add_streaming_migration
+      # Check if columns already exist
+      if column_exists?(:ruby_llm_agents_executions, :streaming)
+        say_status :skip, "streaming column already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "add_streaming_migration.rb.tt",
+        File.join(db_migrate_path, "add_streaming_to_ruby_llm_agents_executions.rb")
+      )
+    end
+
+    def create_add_tracing_migration
+      # Check if columns already exist
+      if column_exists?(:ruby_llm_agents_executions, :trace_id)
+        say_status :skip, "trace_id column already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "add_tracing_migration.rb.tt",
+        File.join(db_migrate_path, "add_tracing_to_ruby_llm_agents_executions.rb")
+      )
+    end
+
+    def create_add_routing_migration
+      # Check if columns already exist
+      if column_exists?(:ruby_llm_agents_executions, :fallback_reason)
+        say_status :skip, "fallback_reason column already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "add_routing_migration.rb.tt",
+        File.join(db_migrate_path, "add_routing_to_ruby_llm_agents_executions.rb")
+      )
+    end
+
+    def create_add_finish_reason_migration
+      # Check if columns already exist
+      if column_exists?(:ruby_llm_agents_executions, :finish_reason)
+        say_status :skip, "finish_reason column already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "add_finish_reason_migration.rb.tt",
+        File.join(db_migrate_path, "add_finish_reason_to_ruby_llm_agents_executions.rb")
+      )
+    end
+
+    def create_add_caching_migration
+      # Check if columns already exist
+      if column_exists?(:ruby_llm_agents_executions, :cache_hit)
+        say_status :skip, "cache_hit column already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "add_caching_migration.rb.tt",
+        File.join(db_migrate_path, "add_caching_to_ruby_llm_agents_executions.rb")
+      )
+    end
+
     def show_post_upgrade_message
       say ""
       say "RubyLLM::Agents upgrade migration created!", :green