ruby_llm-agents 1.3.4 → 2.1.0

data/lib/generators/ruby_llm_agents/install_generator.rb

@@ -14,7 +14,6 @@ module RubyLlmAgents
   #   - Create the initializer at config/initializers/ruby_llm_agents.rb
   #   - Create app/agents/application_agent.rb base class
   #   - Create app/agents/concerns/ directory
-  #   - Create app/workflows/application_workflow.rb base class
   #   - Optionally mount the dashboard engine in routes
   #
   class InstallGenerator < ::Rails::Generators::Base
@@ -38,6 +37,15 @@ module RubyLlmAgents
       )
     end
 
+    def create_execution_details_migration
+      return if options[:skip_migration]
+
+      migration_template(
+        "create_execution_details_migration.rb.tt",
+        File.join(db_migrate_path, "create_ruby_llm_agents_execution_details.rb")
+      )
+    end
+
     def create_initializer
       return if options[:skip_initializer]
 
@@ -51,9 +59,6 @@ module RubyLlmAgents
       empty_directory "app/agents"
       empty_directory "app/agents/concerns"
 
-      # Create workflows directory
-      empty_directory "app/workflows"
-
       # Create tools directory
       empty_directory "app/tools"
     end
@@ -62,19 +67,12 @@ module RubyLlmAgents
       template "application_agent.rb.tt", "app/agents/application_agent.rb"
     end
 
-    def create_application_workflow
-      template "application_workflow.rb.tt", "app/workflows/application_workflow.rb"
-    end
-
     def create_skill_files
       say_status :create, "skill documentation files", :green
 
       # Create agents skill file
       template "skills/AGENTS.md.tt", "app/agents/AGENTS.md"
 
-      # Create workflows skill file
-      template "skills/WORKFLOWS.md.tt", "app/workflows/WORKFLOWS.md"
-
       # Create tools skill file
       template "skills/TOOLS.md.tt", "app/tools/TOOLS.md"
     end
@@ -104,18 +102,16 @@ module RubyLlmAgents
       say "  │   ├── application_agent.rb"
       say "  │   ├── concerns/"
       say "  │   └── AGENTS.md"
-      say "  ├── workflows/"
-      say "  │   ├── application_workflow.rb"
-      say "  │   └── WORKFLOWS.md"
       say "  └── tools/"
       say "      └── TOOLS.md"
       say ""
       say "Skill files (*.md) help AI coding assistants understand how to use this gem."
       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 "  1. Set your API keys in config/initializers/ruby_llm_agents.rb"
+      say "  2. Run migrations: rails db:migrate"
+      say "  3. Generate an agent: rails generate ruby_llm_agents:agent MyAgent query:required"
+      say "  4. Access the dashboard at: /agents"
       say ""
       say "Generator commands:"
       say "  rails generate ruby_llm_agents:agent CustomerSupport query:required"

data/lib/generators/ruby_llm_agents/migrate_structure_generator.rb

@@ -11,14 +11,12 @@ module RubyLlmAgents
   #   app/{root}/image/generators/
   #   app/{root}/audio/speakers/
   #   app/{root}/text/embedders/
-  #   app/{root}/workflows/
   #
   # To:
   #   app/agents/
   #   app/agents/images/
   #   app/agents/audio/
   #   app/agents/embedders/
-  #   app/workflows/
   #
   # Usage:
   #   rails generate ruby_llm_agents:migrate_structure
@@ -72,9 +70,6 @@ module RubyLlmAgents
       "text/embedders" => "agents/embedders",
       "text/moderators" => "agents/moderators",
 
-      # Workflows
-      "workflows" => "workflows",
-
       # Tools
       "tools" => "tools"
     }.freeze
@@ -93,10 +88,7 @@ module RubyLlmAgents
 
       # Text namespaces -> Embedders/Moderators
       /\A(\w+)::Text::(\w+Embedder)\z/ => 'Embedders::\2',
-      /\A(\w+)::Text::(\w+Moderator)\z/ => 'Moderators::\2',
-
-      # Workflows (remove root namespace)
-      /\A(\w+)::(\w+Workflow)\z/ => '\2'
+      /\A(\w+)::Text::(\w+Moderator)\z/ => 'Moderators::\2'
     }.freeze
 
     def check_prerequisites
@@ -120,7 +112,7 @@ module RubyLlmAgents
       say "=" * 60
       say ""
       say "Source: app/#{@source_root_dir}/"
-      say "Target: app/agents/ and app/workflows/"
+      say "Target: app/agents/"
       say ""
 
       @files_to_migrate = []
@@ -274,7 +266,6 @@ module RubyLlmAgents
         say "  │   ├── audio/"
         say "  │   ├── embedders/"
         say "  │   └── moderators/"
-        say "  └── workflows/"
         say ""
         say "Next steps:"
         say "  1. Update class references in your code:"
@@ -327,7 +318,6 @@ module RubyLlmAgents
         image/generators
         audio/speakers
         text/embedders
-        workflows
       ]
 
       old_indicators.any? do |indicator|

data/lib/generators/ruby_llm_agents/restructure_generator.rb

@@ -38,7 +38,6 @@ module RubyLlmAgents
     DIRECTORY_MAPPING = {
       # Top-level under llm/
       "agents" => { category: nil, type: "agents" },
-      "workflows" => { category: nil, type: "workflows" },
       "tools" => { category: nil, type: "tools" },
 
       # Audio group
@@ -173,7 +172,6 @@ module RubyLlmAgents
         say "  ├── text/"
         say "  │   ├── embedders/"
         say "  │   └── moderators/"
-        say "  ├── workflows/"
         say "  └── tools/"
         say ""
         say "Namespaces have been updated to use #{root_namespace}::"

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Migration to add usage counter columns to tenants table
+#
+# These columns enable DB-based budget tracking with atomic SQL increments,
+# replacing the previous cache-based counter approach.
+#
+# Run with: rails db:migrate
+class AddUsageCountersToRubyLLMAgentsTenants < ActiveRecord::Migration<%= migration_version %>
+  def change
+    change_table :ruby_llm_agents_tenants, bulk: true do |t|
+      # Cost counters
+      t.decimal :daily_cost_spent,        precision: 12, scale: 6, default: 0, null: false
+      t.decimal :monthly_cost_spent,      precision: 12, scale: 6, default: 0, null: false
+
+      # Token counters
+      t.bigint :daily_tokens_used,        default: 0, null: false
+      t.bigint :monthly_tokens_used,      default: 0, null: false
+
+      # Execution counters
+      t.bigint :daily_executions_count,   default: 0, null: false
+      t.bigint :monthly_executions_count, default: 0, null: false
+
+      # Error counters
+      t.bigint :daily_error_count,        default: 0, null: false
+      t.bigint :monthly_error_count,      default: 0, null: false
+
+      # Last execution metadata
+      t.datetime :last_execution_at
+      t.string   :last_execution_status
+
+      # Period tracking (for lazy reset)
+      t.date :daily_reset_date
+      t.date :monthly_reset_date
+    end
+  end
+end

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

@@ -14,7 +14,6 @@ class <%= class_name %>Agent < ApplicationAgent
 
     model "<%= options[:model] %>"
     temperature <%= options[:temperature] %>
-    version "1.0"
     # timeout 30  # Per-request timeout in seconds (default: 60)
 
     # ============================================
@@ -104,7 +103,7 @@ class <%= class_name %>Agent < ApplicationAgent
     # end
 
     # Custom metadata to include in execution logs
-    # def execution_metadata
+    # def metadata
     #   { custom_field: "value", request_id: params[:request_id] }
     # end
 

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

@@ -63,7 +63,7 @@ class ApplicationAgent < RubyLLM::Agents::Base
   # end
 
   # Example: Common metadata
-  # def execution_metadata
+  # def metadata
   #   { app_version: Rails.application.config.version }
   # end
 end

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

@@ -47,7 +47,6 @@ module Images
   #
   # METADATA:
   # ---------
-  #   version "1.0"              # Version identifier (affects cache key)
   #   description "My pipeline"  # Human-readable description
   #
   # ============================================================================

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class CreateRubyLLMAgentsExecutionDetails < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :ruby_llm_agents_execution_details do |t|
+      t.references :execution, null: false,
+                   foreign_key: { to_table: :ruby_llm_agents_executions, on_delete: :cascade },
+                   index: { unique: true }
+
+      t.text     :error_message
+      t.text     :system_prompt
+      t.text     :user_prompt
+      t.json     :response,             default: {}
+      t.json     :messages_summary,     default: {}, null: false
+      t.json     :tool_calls,           default: [], null: false
+      t.json     :attempts,             default: [], null: false
+      t.json     :fallback_chain
+      t.json     :parameters,           default: {}, null: false
+      t.string   :routed_to
+      t.json     :classification_result
+      t.datetime :cached_at
+      t.integer  :cache_creation_tokens, default: 0
+
+      t.timestamps
+    end
+  end
+end

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

@@ -49,6 +49,31 @@ class CreateRubyLLMAgentsTenants < ActiveRecord::Migration<%= migration_version
       # Status (for soft-delete/disable)
       t.boolean :active, default: true
 
+      # Usage counter columns (DB-based budget tracking)
+      # Cost counters
+      t.decimal :daily_cost_spent,        precision: 12, scale: 6, default: 0, null: false
+      t.decimal :monthly_cost_spent,      precision: 12, scale: 6, default: 0, null: false
+
+      # Token counters
+      t.bigint :daily_tokens_used,        default: 0, null: false
+      t.bigint :monthly_tokens_used,      default: 0, null: false
+
+      # Execution counters
+      t.bigint :daily_executions_count,   default: 0, null: false
+      t.bigint :monthly_executions_count, default: 0, null: false
+
+      # Error counters
+      t.bigint :daily_error_count,        default: 0, null: false
+      t.bigint :monthly_error_count,      default: 0, null: false
+
+      # Last execution metadata
+      t.datetime :last_execution_at
+      t.string   :last_execution_status
+
+      # Period tracking (for lazy reset)
+      t.date :daily_reset_date
+      t.date :monthly_reset_date
+
       # Extensible metadata (JSON)
       t.json :metadata, null: false, default: {}
 

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

@@ -37,7 +37,6 @@ module Images
 <% end -%>
 
     description "<%= class_name %> image processing pipeline"
-    version "1.0"
 <%- if class_name.include?("::") -%>
 <%- class_name.split("::").length.times do |i| -%>
 <%= "  " * (class_name.split("::").length - i) %>end

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

@@ -5,6 +5,30 @@
 # For more information, see: https://github.com/adham90/ruby_llm-agents
 
 RubyLLM::Agents.configure do |config|
+  # ============================================
+  # LLM Provider API Keys
+  # ============================================
+  # Configure at least one provider. Set these in your environment
+  # or replace ENV[] calls with your keys directly.
+
+  # config.openai_api_key = ENV["OPENAI_API_KEY"]
+  # config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  # config.gemini_api_key = ENV["GOOGLE_API_KEY"]
+
+  # Additional providers:
+  # config.deepseek_api_key = ENV["DEEPSEEK_API_KEY"]
+  # config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+  # config.mistral_api_key = ENV["MISTRAL_API_KEY"]
+  # config.xai_api_key = ENV["XAI_API_KEY"]
+
+  # Custom endpoints (e.g., Azure OpenAI, local Ollama):
+  # config.openai_api_base = "https://your-resource.openai.azure.com"
+  # config.ollama_api_base = "http://localhost:11434"
+
+  # Connection settings:
+  # config.request_timeout = 120
+  # config.max_retries = 3
+
   # ============================================
   # Model Defaults
   # ============================================
@@ -130,22 +154,19 @@ RubyLLM::Agents.configure do |config|
   # 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
+  # Alert handler for governance events
+  # Receives (event, payload) when important events occur:
   #   - :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}")
-  #   }
+  # config.on_alert = ->(event, payload) {
+  #   case event
+  #   when :budget_hard_cap
+  #     Slack::Notifier.new(ENV["SLACK_WEBHOOK"]).ping("Budget exceeded: #{payload[:total_cost]}")
+  #   when :breaker_open
+  #     Rails.logger.error("[Alert] Circuit breaker opened for #{payload[:agent_type]}")
+  #   end
   # }
 
   # ============================================

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

@@ -5,109 +5,79 @@ class CreateRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_versi
     create_table :ruby_llm_agents_executions do |t|
       # Agent identification
       t.string :agent_type, null: false
-      t.string :agent_version, default: "1.0"
+      t.string :execution_type, null: false, default: "chat"
 
       # Model configuration
       t.string :model_id, null: false
       t.string :model_provider
       t.decimal :temperature, precision: 3, scale: 2
+      t.string :chosen_model_id
+
+      # Status
+      t.string :status, null: false, default: "running"
+      t.string :finish_reason
+      t.string :error_class
 
       # Timing
       t.datetime :started_at, null: false
       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
-
       # Token usage
-      t.integer :input_tokens
-      t.integer :output_tokens
-      t.integer :total_tokens
+      t.integer :input_tokens, default: 0
+      t.integer :output_tokens, default: 0
+      t.integer :total_tokens, default: 0
       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 (JSON - works with PostgreSQL, MySQL, SQLite3)
-      t.json :parameters, null: false, default: {}
-      t.json :response, default: {}
-      t.json :metadata, null: false, default: {}
+      # Caching
+      t.boolean :cache_hit, default: false
 
-      # Error tracking
-      t.string :error_class
-      t.text :error_message
+      # Streaming
+      t.boolean :streaming, default: false
+
+      # Retry / Fallback
+      t.integer :attempts_count, default: 1, null: false
+
+      # Tool calls
+      t.integer :tool_calls_count, default: 0, null: false
+
+      # Distributed tracing
+      t.string :trace_id
+      t.string :request_id
+
+      # Execution hierarchy (self-join)
+      t.bigint :parent_execution_id
+      t.bigint :root_execution_id
 
-      # Prompts (for history/changelog)
-      t.text :system_prompt
-      t.text :user_prompt
+      # Multi-tenancy
+      t.string :tenant_id
 
-      # Tool calls tracking
-      t.json :tool_calls, null: false, default: []
-      t.integer :tool_calls_count, null: false, default: 0
+      # Conversation context
+      t.integer :messages_count, default: 0, null: false
 
-      # Workflow orchestration
-      t.string :workflow_id
-      t.string :workflow_type
-      t.string :workflow_step
-      t.string :routed_to
-      t.json :classification_result
+      # Flexible storage (niche fields, trace context, custom tags)
+      t.json :metadata, null: false, default: {}
 
       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
+    # Indexes: only what's actually queried
     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
-
-    # Tracing indexes
-    add_index :ruby_llm_agents_executions, :request_id
+    add_index :ruby_llm_agents_executions, :status
+    add_index :ruby_llm_agents_executions, :created_at
+    add_index :ruby_llm_agents_executions, [:tenant_id, :created_at]
+    add_index :ruby_llm_agents_executions, [:tenant_id, :status]
     add_index :ruby_llm_agents_executions, :trace_id
+    add_index :ruby_llm_agents_executions, :request_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
-
-    # Tool calls index
-    add_index :ruby_llm_agents_executions, :tool_calls_count
-
-    # Workflow indexes
-    add_index :ruby_llm_agents_executions, :workflow_id
-    add_index :ruby_llm_agents_executions, :workflow_type
-    add_index :ruby_llm_agents_executions, [:workflow_id, :workflow_step]
-
     # Foreign keys for execution hierarchy
     add_foreign_key :ruby_llm_agents_executions, :ruby_llm_agents_executions,
                     column: :parent_execution_id, on_delete: :nullify
@@ -116,7 +86,6 @@ class CreateRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_versi
 
     # 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/templates/remove_agent_version_migration.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Migration to remove agent_version column (deprecated in favor of content-based cache keys)
+class RemoveAgentVersionFromRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Remove the composite index first (if it exists)
+    remove_index :ruby_llm_agents_executions, [:agent_type, :agent_version],
+                 if_exists: true
+
+    # Remove the deprecated column
+    remove_column :ruby_llm_agents_executions, :agent_version, :string, default: "1.0"
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Migration to remove workflow columns (workflows feature removed)
+class RemoveWorkflowColumnsFromRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Remove indexes first
+    remove_index :ruby_llm_agents_executions, [:workflow_id, :workflow_step],
+                 if_exists: true
+    remove_index :ruby_llm_agents_executions, :workflow_id,
+                 if_exists: true
+    remove_index :ruby_llm_agents_executions, :workflow_type,
+                 if_exists: true
+
+    # Remove the columns
+    remove_column :ruby_llm_agents_executions, :workflow_id, :string
+    remove_column :ruby_llm_agents_executions, :workflow_type, :string
+    remove_column :ruby_llm_agents_executions, :workflow_step, :string
+  end
+end

data/lib/generators/ruby_llm_agents/templates/skills/AGENTS.md.tt

@@ -15,7 +15,6 @@ class MyAgent < ApplicationAgent
   # Configuration
   model "gpt-4o"
   temperature 0.0
-  version "1.0"
 
   # Parameters
   param :query, required: true
@@ -60,7 +59,6 @@ app/agents/
 |--------|-------------|---------|
 | `model` | LLM model to use | `model "gpt-4o"` |
 | `temperature` | Response randomness (0.0-2.0) | `temperature 0.7` |
-| `version` | Cache invalidation version | `version "2.0"` |
 | `timeout` | Request timeout in seconds | `timeout 30` |
 | `description` | Human-readable description | `description "Searches documents"` |
 
@@ -183,10 +181,10 @@ def cache_key_data
 end
 ```
 
-### `execution_metadata`
+### `metadata`
 Add custom data to execution logs:
 ```ruby
-def execution_metadata
+def metadata
   { request_id: params[:request_id] }
 end
 ```

data/lib/generators/ruby_llm_agents/templates/skills/IMAGE_PIPELINES.md.tt

@@ -129,7 +129,6 @@ result = Images::SmartPipeline.call(
 module Images
   class EcommercePipeline < ApplicationImagePipeline
     description "Generate and process product images"
-    version "1.0"
 
     step :generate, generator: ProductGenerator
     step :upscale, upscaler: PhotoUpscaler, scale: 2