ruby_llm-agents 0.3.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40771a5bbdc5c7baea26c0900c6715e3e1033569154ebeb0d7cd60eff83d1389
-  data.tar.gz: bedbf16ff8717ebcdca79aa256f9aae489677baad1b848baa38d4d485b87c803
+  metadata.gz: 4b0d9c86b501d77defab3fb33ae73b69548d332dad116dac76a56ac1dcaa3a60
+  data.tar.gz: 6ead43212abcb265fbb73b8daec26b49f8558c8962630d42279e3cf67328b263
 SHA512:
-  metadata.gz: 3202614bf8c8209a1e9a589137440c804d2fcdc8fa2045840e4429963e06a0b4b1b25f82da99f6e1a5e3090afa1b149dec500d87ce59c09de946a3293e728962
-  data.tar.gz: '08d565511fc883fdb83377e4993dbd699a5ecce23cbfdc454c6372279fc275165dddfc5c0b4b4d1010f1dde3c4acdaca4f260d0c07b6cc7b9ad81e7b13cd4b41'
+  metadata.gz: f5307aba39ba108d6104a39fcf842ab262d93237f07cc208291403f4fd1d23f604783b915c9236e85551caa0bf6e95bbe253159b4893cf174c3fb1dd12febe29
+  data.tar.gz: 0a72c3e6ae5912a9b694bd821ce514f6f4de8af7c99487d88bc9051ee80122f2f5e0e7bf97ec698d951a1e70012e676b15a21b9abbb22c777c9b677463d567e7

data/README.md

@@ -1,5 +1,7 @@
 # RubyLLM::Agents
 
+> **AI Agents:** For comprehensive documentation optimized for AI consumption, see [LLMS.txt](LLMS.txt)
+
 > **Production-ready Rails engine for building, managing, and monitoring LLM-powered AI agents**
 
 [![Gem Version](https://badge.fury.io/rb/ruby_llm-agents.svg)](https://rubygems.org/gems/ruby_llm-agents)
@@ -22,11 +24,12 @@ Build intelligent AI agents in Ruby with a clean DSL, automatic execution tracki
 
 | Feature | Description | Docs |
 |---------|-------------|------|
-| **Agent DSL** | Declarative configuration with model, temperature, parameters | [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) |
-| **Execution Tracking** | Automatic logging with token usage and cost analytics | [Tracking](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
-| **Cost Analytics** | Track spending by agent, model, and time period | [Analytics](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
-| **Reliability** | Automatic retries, model fallbacks, circuit breakers | [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) |
+| **Agent DSL** | Declarative configuration with model, temperature, parameters, description | [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) |
+| **Execution Tracking** | Automatic logging with token usage, cost analytics, and fallback tracking | [Tracking](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
+| **Cost Analytics** | Track spending by agent, model, tenant, and time period | [Analytics](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
+| **Reliability** | Automatic retries, model fallbacks, circuit breakers with block DSL | [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) |
 | **Budget Controls** | Daily/monthly limits with hard and soft enforcement | [Budgets](https://github.com/adham90/ruby_llm-agents/wiki/Budget-Controls) |
+| **Multi-Tenancy** | Per-tenant budgets, circuit breakers, and execution isolation | [Multi-Tenancy](https://github.com/adham90/ruby_llm-agents/wiki/Multi-Tenancy) |
 | **Workflows** | Pipelines, parallel execution, conditional routers | [Workflows](https://github.com/adham90/ruby_llm-agents/wiki/Workflows) |
 | **Dashboard** | Real-time Turbo-powered monitoring UI | [Dashboard](https://github.com/adham90/ruby_llm-agents/wiki/Dashboard) |
 | **Streaming** | Real-time response streaming with TTFT tracking | [Streaming](https://github.com/adham90/ruby_llm-agents/wiki/Streaming) |
@@ -116,13 +119,18 @@ See [Conversation History](https://github.com/adham90/ruby_llm-agents/wiki/Conve
 
 ## Documentation
 
+> **Note:** Wiki content lives in the [`wiki/`](wiki/) folder. To sync changes to the [GitHub Wiki](https://github.com/adham90/ruby_llm-agents/wiki), run `./scripts/sync-wiki.sh`.
+
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](https://github.com/adham90/ruby_llm-agents/wiki/Getting-Started) | Installation, configuration, first agent |
-| [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) | All DSL options: model, temperature, params, caching |
-| [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) | Retries, fallbacks, circuit breakers, timeouts |
+| [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) | All DSL options: model, temperature, params, caching, description |
+| [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) | Retries, fallbacks, circuit breakers, timeouts, reliability block |
 | [Workflows](https://github.com/adham90/ruby_llm-agents/wiki/Workflows) | Pipelines, parallel execution, routers |
 | [Budget Controls](https://github.com/adham90/ruby_llm-agents/wiki/Budget-Controls) | Spending limits, alerts, enforcement |
+| [Multi-Tenancy](https://github.com/adham90/ruby_llm-agents/wiki/Multi-Tenancy) | Per-tenant budgets, isolation, configuration |
+| [Testing Agents](https://github.com/adham90/ruby_llm-agents/wiki/Testing-Agents) | RSpec patterns, mocking, dry_run mode |
+| [Error Handling](https://github.com/adham90/ruby_llm-agents/wiki/Error-Handling) | Error types, recovery patterns |
 | [Dashboard](https://github.com/adham90/ruby_llm-agents/wiki/Dashboard) | Setup, authentication, analytics |
 | [Production](https://github.com/adham90/ruby_llm-agents/wiki/Production-Deployment) | Deployment best practices, background jobs |
 | [API Reference](https://github.com/adham90/ruby_llm-agents/wiki/API-Reference) | Complete class documentation |
@@ -135,19 +143,22 @@ Build resilient agents with built-in fault tolerance:
 ```ruby
 class ReliableAgent < ApplicationAgent
   model "gpt-4o"
+  description "A resilient agent with automatic retries and fallbacks"
 
-  # Retry on failures with exponential backoff
+  # Option 1: Individual DSL methods
   retries max: 3, backoff: :exponential
-
-  # Fall back to alternative models
   fallback_models "gpt-4o-mini", "claude-3-5-sonnet"
-
-  # Prevent cascading failures
   circuit_breaker errors: 10, within: 60, cooldown: 300
-
-  # Maximum time for all attempts
   total_timeout 30
 
+  # Option 2: Grouped reliability block (equivalent to above)
+  reliability do
+    retries max: 3, backoff: :exponential
+    fallback_models "gpt-4o-mini", "claude-3-5-sonnet"
+    circuit_breaker errors: 10, within: 60, cooldown: 300
+    total_timeout 30
+  end
+
   param :query, required: true
 
   def user_prompt
@@ -156,6 +167,28 @@ class ReliableAgent < ApplicationAgent
 end
 ```
 
+### Enhanced Result Object
+
+The result object provides detailed execution metadata:
+
+```ruby
+result = ReliableAgent.call(query: "test")
+
+# Basic response
+result.content           # => { ... }
+result.success?          # => true
+
+# Reliability info
+result.attempts_count    # => 2 (if retry occurred)
+result.used_fallback?    # => true (if fallback model used)
+result.chosen_model_id   # => "gpt-4o-mini" (actual model used)
+
+# Cost & timing
+result.total_cost        # => 0.00025
+result.total_tokens      # => 150
+result.duration_ms       # => 850
+```
+
 ## Workflow Orchestration
 
 Compose agents into complex workflows:

data/app/controllers/ruby_llm/agents/api_configurations_controller.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Controller for managing API configurations
+    #
+    # Provides CRUD operations for global and tenant-specific API
+    # configurations, including API keys and connection settings.
+    #
+    # @see ApiConfiguration
+    # @api private
+    class ApiConfigurationsController < ApplicationController
+      before_action :ensure_table_exists
+      before_action :set_global_config, only: [:show, :edit, :update]
+      before_action :set_tenant_config, only: [:tenant, :edit_tenant, :update_tenant]
+
+      # Displays the global API configuration
+      #
+      # @return [void]
+      def show
+        @resolved = ApiConfiguration.resolve
+        @provider_statuses = @resolved.provider_statuses_with_source
+      end
+
+      # Renders the edit form for global configuration
+      #
+      # @return [void]
+      def edit
+        @resolved = ApiConfiguration.resolve
+      end
+
+      # Updates the global API configuration
+      #
+      # @return [void]
+      def update
+        if @config.update(api_configuration_params)
+          log_configuration_change(@config, "global")
+          redirect_to edit_api_configuration_path, notice: "API configuration updated successfully"
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      # Displays tenant-specific API configuration
+      #
+      # @return [void]
+      def tenant
+        @resolved = ApiConfiguration.resolve(tenant_id: params[:tenant_id])
+        @provider_statuses = @resolved.provider_statuses_with_source
+        @tenant_budget = TenantBudget.for_tenant(params[:tenant_id])
+      end
+
+      # Renders the edit form for tenant configuration
+      #
+      # @return [void]
+      def edit_tenant
+        @resolved = ApiConfiguration.resolve(tenant_id: @tenant_id)
+      end
+
+      # Updates a tenant-specific API configuration
+      #
+      # @return [void]
+      def update_tenant
+        if @config.update(api_configuration_params)
+          log_configuration_change(@config, "tenant:#{params[:tenant_id]}")
+          redirect_to edit_tenant_api_configuration_path(params[:tenant_id]),
+                      notice: "Tenant API configuration updated successfully"
+        else
+          render :edit_tenant, status: :unprocessable_entity
+        end
+      end
+
+      # Tests API key validity for a specific provider
+      # (Optional - can be used for AJAX validation)
+      #
+      # @return [void]
+      def test_connection
+        provider = params[:provider]
+        api_key = params[:api_key]
+
+        result = test_provider_connection(provider, api_key)
+
+        render json: {
+          success: result[:success],
+          message: result[:message],
+          models: result[:models]
+        }
+      rescue StandardError => e
+        render json: { success: false, message: e.message }
+      end
+
+      private
+
+      # Ensures the api_configurations table exists
+      def ensure_table_exists
+        return if ApiConfiguration.table_exists?
+
+        flash[:alert] = "API configurations table not found. Run the generator: rails generate ruby_llm_agents:api_configuration"
+        redirect_to root_path
+      end
+
+      # Sets the global configuration (creates if not exists)
+      def set_global_config
+        @config = ApiConfiguration.global
+      end
+
+      # Sets the tenant-specific configuration (creates if not exists)
+      def set_tenant_config
+        @tenant_id = params[:tenant_id]
+        raise ActionController::RoutingError, "Tenant ID required" if @tenant_id.blank?
+
+        @config = ApiConfiguration.for_tenant!(@tenant_id)
+      end
+
+      # Strong parameters for API configuration
+      #
+      # @return [ActionController::Parameters]
+      def api_configuration_params
+        params.require(:api_configuration).permit(
+          # API Keys
+          :openai_api_key,
+          :anthropic_api_key,
+          :gemini_api_key,
+          :deepseek_api_key,
+          :mistral_api_key,
+          :perplexity_api_key,
+          :openrouter_api_key,
+          :gpustack_api_key,
+          :xai_api_key,
+          :ollama_api_key,
+          # AWS Bedrock
+          :bedrock_api_key,
+          :bedrock_secret_key,
+          :bedrock_session_token,
+          :bedrock_region,
+          # Vertex AI
+          :vertexai_credentials,
+          :vertexai_project_id,
+          :vertexai_location,
+          # Endpoints
+          :openai_api_base,
+          :gemini_api_base,
+          :ollama_api_base,
+          :gpustack_api_base,
+          :xai_api_base,
+          # OpenAI Options
+          :openai_organization_id,
+          :openai_project_id,
+          # Default Models
+          :default_model,
+          :default_embedding_model,
+          :default_image_model,
+          :default_moderation_model,
+          # Connection Settings
+          :request_timeout,
+          :max_retries,
+          :retry_interval,
+          :retry_backoff_factor,
+          :retry_interval_randomness,
+          :http_proxy,
+          # Inheritance
+          :inherit_global_defaults
+        ).tap do |permitted|
+          # Remove blank API keys to prevent overwriting with empty values
+          # This allows users to submit forms without touching existing keys
+          ApiConfiguration::API_KEY_ATTRIBUTES.each do |key|
+            permitted.delete(key) if permitted[key].blank?
+          end
+        end
+      end
+
+      # Logs configuration changes for audit purposes
+      #
+      # @param config [ApiConfiguration] The configuration that changed
+      # @param scope [String] The scope identifier
+      def log_configuration_change(config, scope)
+        changed_fields = config.previous_changes.keys.reject { |k| k.end_with?("_at") }
+        return if changed_fields.empty?
+
+        # Mask sensitive fields in the log
+        masked_changes = changed_fields.map do |field|
+          if field.include?("api_key") || field.include?("secret") || field.include?("credentials")
+            "#{field}: [REDACTED]"
+          else
+            "#{field}: #{config.previous_changes[field].last}"
+          end
+        end
+
+        Rails.logger.info(
+          "[RubyLLM::Agents] API configuration updated for #{scope}: #{masked_changes.join(', ')}"
+        )
+      end
+
+      # Tests connection to a specific provider
+      #
+      # @param provider [String] Provider key
+      # @param api_key [String] API key to test
+      # @return [Hash] Test result with success, message, and models
+      def test_provider_connection(provider, api_key)
+        # This is a placeholder - actual implementation would depend on
+        # RubyLLM's ability to list models or make a test request
+        case provider
+        when "openai"
+          # Example: Try to list models
+          { success: true, message: "Connection successful", models: [] }
+        when "anthropic"
+          { success: true, message: "Connection successful", models: [] }
+        else
+          { success: false, message: "Provider not supported for testing" }
+        end
+      end
+    end
+  end
+end

data/app/controllers/ruby_llm/agents/{settings_controller.rb → system_config_controller.rb}

@@ -2,14 +2,14 @@
 
 module RubyLLM
   module Agents
-    # Controller for displaying global configuration settings
+    # Controller for displaying system configuration
     #
     # Shows all configuration options from RubyLLM::Agents.configuration
     # in a read-only dashboard view.
     #
     # @api private
-    class SettingsController < ApplicationController
-      # Displays the global configuration settings
+    class SystemConfigController < ApplicationController
+      # Displays the system configuration
       #
       # @return [void]
       def show

data/app/controllers/ruby_llm/agents/tenants_controller.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Controller for managing tenant budgets
+    #
+    # Provides CRUD operations for viewing and editing tenant budget
+    # configurations, including cost limits and token limits.
+    #
+    # @see TenantBudget For budget configuration model
+    # @api private
+    class TenantsController < ApplicationController
+      # Lists all tenant budgets
+      #
+      # @return [void]
+      def index
+        @tenants = TenantBudget.order(:name, :tenant_id)
+      end
+
+      # Shows a single tenant's budget details
+      #
+      # @return [void]
+      def show
+        @tenant = TenantBudget.find(params[:id])
+        @executions = tenant_executions(@tenant.tenant_id).recent.limit(10)
+        @usage_stats = calculate_usage_stats(@tenant)
+      end
+
+      # Renders the edit form for a tenant budget
+      #
+      # @return [void]
+      def edit
+        @tenant = TenantBudget.find(params[:id])
+      end
+
+      # Updates a tenant budget
+      #
+      # @return [void]
+      def update
+        @tenant = TenantBudget.find(params[:id])
+        if @tenant.update(tenant_params)
+          redirect_to tenant_path(@tenant), notice: "Tenant updated successfully"
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      private
+
+      # Strong parameters for tenant budget
+      #
+      # @return [ActionController::Parameters] Permitted parameters
+      def tenant_params
+        params.require(:tenant_budget).permit(
+          :name, :daily_limit, :monthly_limit,
+          :daily_token_limit, :monthly_token_limit,
+          :enforcement
+        )
+      end
+
+      # Returns executions scoped to a specific tenant
+      #
+      # @param tenant_id [String] The tenant identifier
+      # @return [ActiveRecord::Relation] Executions for the tenant
+      def tenant_executions(tenant_id)
+        Execution.by_tenant(tenant_id)
+      end
+
+      # Calculates usage statistics for a tenant
+      #
+      # @param tenant [TenantBudget] The tenant budget record
+      # @return [Hash] Usage statistics
+      def calculate_usage_stats(tenant)
+        scope = tenant_executions(tenant.tenant_id)
+        today_scope = scope.where("created_at >= ?", Time.current.beginning_of_day)
+        month_scope = scope.where("created_at >= ?", Time.current.beginning_of_month)
+
+        daily_spend = today_scope.sum(:total_cost) || 0
+        monthly_spend = month_scope.sum(:total_cost) || 0
+        daily_tokens = today_scope.sum(:total_tokens) || 0
+        monthly_tokens = month_scope.sum(:total_tokens) || 0
+
+        {
+          daily_spend: daily_spend,
+          monthly_spend: monthly_spend,
+          daily_tokens: daily_tokens,
+          monthly_tokens: monthly_tokens,
+          daily_spend_percentage: percentage_used(daily_spend, tenant.effective_daily_limit),
+          monthly_spend_percentage: percentage_used(monthly_spend, tenant.effective_monthly_limit),
+          daily_token_percentage: percentage_used(daily_tokens, tenant.effective_daily_token_limit),
+          monthly_token_percentage: percentage_used(monthly_tokens, tenant.effective_monthly_token_limit),
+          total_executions: scope.count,
+          total_cost: scope.sum(:total_cost) || 0,
+          total_tokens: scope.sum(:total_tokens) || 0
+        }
+      end
+
+      # Calculates percentage used
+      #
+      # @param current [Numeric] Current usage
+      # @param limit [Numeric, nil] The limit
+      # @return [Float] Percentage used (0-100+)
+      def percentage_used(current, limit)
+        return 0 if limit.nil? || limit.to_f <= 0
+        (current.to_f / limit.to_f * 100).round(1)
+      end
+    end
+  end
+end