ruby_llm-agents 0.5.0 → 1.0.0

data/lib/ruby_llm/agents/core/errors.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Base error class for RubyLLM::Agents
+    class Error < StandardError; end
+
+    # ============================================================
+    # Pipeline Errors
+    # ============================================================
+
+    # Base class for pipeline-related errors
+    class PipelineError < Error; end
+
+    # ============================================================
+    # Reliability Errors
+    # ============================================================
+
+    # Base class for reliability-related errors
+    class ReliabilityError < Error; end
+
+    # Raised when an error is retryable (transient)
+    class RetryableError < ReliabilityError; end
+
+    # Raised when a circuit breaker is open
+    class CircuitOpenError < ReliabilityError
+      # @return [String] The model that has an open circuit
+      attr_reader :model
+
+      def initialize(message = nil, model: nil)
+        @model = model
+        super(message || "Circuit breaker is open#{model ? " for #{model}" : ""}")
+      end
+    end
+
+    # Raised when total timeout is exceeded across all attempts
+    class TotalTimeoutError < ReliabilityError
+      # @return [Float] The timeout that was exceeded
+      attr_reader :timeout
+
+      # @return [Float] The elapsed time
+      attr_reader :elapsed
+
+      def initialize(message = nil, timeout: nil, elapsed: nil)
+        @timeout = timeout
+        @elapsed = elapsed
+        super(message || "Total timeout of #{timeout}s exceeded (elapsed: #{elapsed&.round(2)}s)")
+      end
+    end
+
+    # Raised when all models (primary + fallbacks) fail
+    class AllModelsFailedError < ReliabilityError
+      # @return [Array<Hash>] Details of each failed attempt
+      attr_reader :attempts
+
+      def initialize(message = nil, attempts: [])
+        @attempts = attempts
+        models = attempts.map { |a| a[:model] }.compact.join(", ")
+        super(message || "All models failed: #{models}")
+      end
+    end
+
+    # ============================================================
+    # Budget Errors
+    # ============================================================
+
+    # Base class for budget-related errors
+    class BudgetError < Error; end
+
+    # Raised when budget is exceeded
+    class BudgetExceededError < BudgetError
+      # @return [String, nil] The tenant ID
+      attr_reader :tenant_id
+
+      # @return [String, nil] The budget type (daily, monthly, etc.)
+      attr_reader :budget_type
+
+      def initialize(message = nil, tenant_id: nil, budget_type: nil)
+        @tenant_id = tenant_id
+        @budget_type = budget_type
+        super(message || "Budget exceeded#{tenant_id ? " for tenant #{tenant_id}" : ""}")
+      end
+    end
+
+    # ============================================================
+    # Configuration Errors
+    # ============================================================
+
+    # Raised for configuration issues
+    class ConfigurationError < Error; end
+
+    # Raised when content is flagged during moderation
+    #
+    # Contains the full moderation result and the phase where
+    # the content was flagged.
+    #
+    # @example Handling moderation errors
+    #   begin
+    #     result = MyAgent.call(message: user_input)
+    #   rescue RubyLLM::Agents::ModerationError => e
+    #     puts "Content blocked: #{e.flagged_categories.join(', ')}"
+    #     puts "Phase: #{e.phase}"
+    #     puts "Scores: #{e.category_scores}"
+    #   end
+    #
+    # @api public
+    class ModerationError < Error
+      # @return [Object] The raw moderation result from RubyLLM
+      attr_reader :moderation_result
+
+      # @return [Symbol] The phase where content was flagged (:input or :output)
+      attr_reader :phase
+
+      # Creates a new ModerationError
+      #
+      # @param moderation_result [Object] The moderation result from RubyLLM
+      # @param phase [Symbol] The phase where content was flagged
+      def initialize(moderation_result, phase)
+        @moderation_result = moderation_result
+        @phase = phase
+
+        categories = moderation_result.flagged_categories
+        category_list = categories.respond_to?(:join) ? categories.join(", ") : categories.to_s
+
+        super("Content flagged during #{phase} moderation: #{category_list}")
+      end
+
+      # Returns the flagged categories from the moderation result
+      #
+      # @return [Array<String, Symbol>] List of flagged categories
+      def flagged_categories
+        moderation_result.flagged_categories
+      end
+
+      # Returns the category scores from the moderation result
+      #
+      # @return [Hash{String, Symbol => Float}] Category to score mapping
+      def category_scores
+        moderation_result.category_scores
+      end
+
+      # Returns whether the moderation result was flagged
+      #
+      # @return [Boolean] Always true for ModerationError
+      def flagged?
+        true
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/{instrumentation.rb → core/instrumentation.rb}

@@ -627,6 +627,9 @@ module RubyLLM
         # during multi-turn conversations (when tools are used)
         tool_calls_data = respond_to?(:accumulated_tool_calls) ? accumulated_tool_calls : []
 
+        # Extract thinking data if present
+        thinking_data = safe_extract_thinking_data(response)
+
         {
           input_tokens: safe_response_value(response, :input_tokens),
           output_tokens: safe_response_value(response, :output_tokens),
@@ -637,7 +640,7 @@ module RubyLLM
           response: safe_serialize_response(response),
           tool_calls: tool_calls_data || [],
           tool_calls_count: tool_calls_data&.size || 0
-        }.compact
+        }.merge(thinking_data).compact
       end
 
       # Extracts finish reason from response, normalizing to standard values
@@ -665,6 +668,24 @@ module RubyLLM
         end
       end
 
+      # Extracts thinking data from response
+      #
+      # Handles different response structures from various providers.
+      # The thinking object typically has text, signature, and tokens.
+      #
+      # @param response [RubyLLM::Message] The LLM response
+      # @return [Hash] Thinking data (empty if none present)
+      def safe_extract_thinking_data(response)
+        thinking = safe_response_value(response, :thinking)
+        return {} unless thinking
+
+        {
+          thinking_text: thinking.respond_to?(:text) ? thinking.text : thinking[:text],
+          thinking_signature: thinking.respond_to?(:signature) ? thinking.signature : thinking[:signature],
+          thinking_tokens: thinking.respond_to?(:tokens) ? thinking.tokens : thinking[:tokens]
+        }.compact
+      end
+
       # Extracts routing/retry tracking data from attempt tracker
       #
       # Analyzes the execution attempts to determine:

data/lib/ruby_llm/agents/core/llm_tenant.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module RubyLLM
+  module Agents
+    # DSL for declaring Rails models as LLM tenants
+    #
+    # Provides automatic budget management and usage tracking when included
+    # in ActiveRecord models. Models using this concern can be passed as
+    # the `tenant:` parameter to agents.
+    #
+    # @example Basic usage
+    #   class Organization < ApplicationRecord
+    #     llm_tenant
+    #   end
+    #
+    # @example With custom ID method
+    #   class Organization < ApplicationRecord
+    #     llm_tenant id: :slug
+    #   end
+    #
+    # @example With auto-created budget
+    #   class Organization < ApplicationRecord
+    #     llm_tenant id: :slug, budget: true
+    #   end
+    #
+    # @example With limits (auto-creates budget)
+    #   class Organization < ApplicationRecord
+    #     llm_tenant(
+    #       id: :slug,
+    #       name: :company_name,
+    #       limits: {
+    #         daily_cost: 100,
+    #         monthly_cost: 1000,
+    #         daily_executions: 500
+    #       },
+    #       enforcement: :hard
+    #     )
+    #   end
+    #
+    # @example With API keys from model columns/methods
+    #   class Organization < ApplicationRecord
+    #     encrypts :openai_api_key, :anthropic_api_key  # Rails 7+ encryption
+    #
+    #     llm_tenant(
+    #       id: :slug,
+    #       api_keys: {
+    #         openai: :openai_api_key,        # column name
+    #         anthropic: :anthropic_api_key,  # column name
+    #         gemini: :fetch_gemini_key       # custom method
+    #       }
+    #     )
+    #
+    #     def fetch_gemini_key
+    #       Vault.read("secret/#{slug}/gemini")
+    #     end
+    #   end
+    #
+    # @see RubyLLM::Agents::TenantBudget
+    # @api public
+    module LLMTenant
+      extend ActiveSupport::Concern
+
+      included do
+        # Executions tracked for this tenant
+        has_many :llm_executions,
+                 class_name: "RubyLLM::Agents::Execution",
+                 as: :tenant_record,
+                 dependent: :nullify
+
+        # Budget association (optional)
+        has_one :llm_budget,
+                class_name: "RubyLLM::Agents::TenantBudget",
+                as: :tenant_record,
+                dependent: :destroy
+
+        # Store options at class level
+        class_attribute :llm_tenant_options, default: {}
+      end
+
+      class_methods do
+        # Declares this model as an LLM tenant
+        #
+        # @param id [Symbol] Method to call for tenant_id string (default: :id)
+        # @param name [Symbol] Method for budget display name (default: :to_s)
+        # @param budget [Boolean] Auto-create TenantBudget on model creation (default: false)
+        # @param limits [Hash] Default budget limits (implies budget: true)
+        # @param enforcement [Symbol] Budget enforcement mode (:none, :soft, :hard)
+        # @param inherit_global [Boolean] Inherit from global config (default: true)
+        # @param api_keys [Hash] Provider API keys mapping (e.g., { openai: :openai_api_key })
+        # @return [void]
+        def llm_tenant(id: :id, name: :to_s, budget: false, limits: nil, enforcement: nil, inherit_global: true, api_keys: nil)
+          self.llm_tenant_options = {
+            id: id,
+            name: name,
+            budget: budget || limits.present?,
+            limits: normalize_limits(limits),
+            enforcement: enforcement,
+            inherit_global: inherit_global,
+            api_keys: api_keys
+          }
+
+          # Auto-create budget callback
+          after_create :create_default_llm_budget if llm_tenant_options[:budget]
+        end
+
+        private
+
+        # Normalizes the limits hash to internal column names
+        #
+        # @param limits [Hash, nil] User-provided limits
+        # @return [Hash] Normalized limits
+        def normalize_limits(limits)
+          return {} if limits.blank?
+
+          {
+            daily_cost: limits[:daily_cost],
+            monthly_cost: limits[:monthly_cost],
+            daily_tokens: limits[:daily_tokens],
+            monthly_tokens: limits[:monthly_tokens],
+            daily_executions: limits[:daily_executions],
+            monthly_executions: limits[:monthly_executions]
+          }.compact
+        end
+      end
+
+      # Returns the tenant_id string for this model
+      #
+      # @return [String] The tenant identifier
+      def llm_tenant_id
+        id_method = self.class.llm_tenant_options[:id] || :id
+        send(id_method).to_s
+      end
+
+      # Returns API keys resolved from the DSL configuration
+      #
+      # Maps provider names (e.g., :openai, :anthropic) to their resolved values
+      # by calling the configured method/column on this model instance.
+      #
+      # @return [Hash] Provider to API key mapping (e.g., { openai: "sk-..." })
+      # @example
+      #   org.llm_api_keys
+      #   # => { openai: "sk-abc123", anthropic: "sk-ant-xyz789" }
+      def llm_api_keys
+        api_keys_config = self.class.llm_tenant_options[:api_keys]
+        return {} if api_keys_config.blank?
+
+        api_keys_config.transform_values do |method_name|
+          value = send(method_name)
+          value.presence
+        end.compact
+      end
+
+      # Returns cost for a given period
+      #
+      # @param period [Symbol, Range, nil] Time period (:today, :this_month, etc.)
+      # @return [BigDecimal] Total cost
+      def llm_cost(period: nil)
+        scope = llm_executions
+        scope = apply_period_scope(scope, period) if period
+        scope.sum(:total_cost) || 0
+      end
+
+      # Returns cost for today
+      #
+      # @return [BigDecimal] Today's cost
+      def llm_cost_today
+        llm_cost(period: :today)
+      end
+
+      # Returns cost for this month
+      #
+      # @return [BigDecimal] This month's cost
+      def llm_cost_this_month
+        llm_cost(period: :this_month)
+      end
+
+      # Returns token count for a given period
+      #
+      # @param period [Symbol, Range, nil] Time period
+      # @return [Integer] Total tokens
+      def llm_tokens(period: nil)
+        scope = llm_executions
+        scope = apply_period_scope(scope, period) if period
+        scope.sum(:total_tokens) || 0
+      end
+
+      # Returns tokens for today
+      #
+      # @return [Integer] Today's tokens
+      def llm_tokens_today
+        llm_tokens(period: :today)
+      end
+
+      # Returns tokens for this month
+      #
+      # @return [Integer] This month's tokens
+      def llm_tokens_this_month
+        llm_tokens(period: :this_month)
+      end
+
+      # Returns execution count for a given period
+      #
+      # @param period [Symbol, Range, nil] Time period
+      # @return [Integer] Execution count
+      def llm_execution_count(period: nil)
+        scope = llm_executions
+        scope = apply_period_scope(scope, period) if period
+        scope.count
+      end
+
+      # Returns executions for today
+      #
+      # @return [Integer] Today's execution count
+      def llm_executions_today
+        llm_execution_count(period: :today)
+      end
+
+      # Returns executions for this month
+      #
+      # @return [Integer] This month's execution count
+      def llm_executions_this_month
+        llm_execution_count(period: :this_month)
+      end
+
+      # Returns a usage summary for a given period
+      #
+      # @param period [Symbol] Time period (default: :this_month)
+      # @return [Hash] Usage summary with cost, tokens, and executions
+      def llm_usage_summary(period: :this_month)
+        {
+          cost: llm_cost(period: period),
+          tokens: llm_tokens(period: period),
+          executions: llm_execution_count(period: period),
+          period: period
+        }
+      end
+
+      # Returns or builds the associated TenantBudget
+      #
+      # @return [TenantBudget] The budget record
+      def llm_budget
+        super || build_llm_budget(tenant_id: llm_tenant_id)
+      end
+
+      # Configure budget with a block
+      #
+      # @yield [budget] The budget to configure
+      # @return [TenantBudget] The saved budget
+      def llm_configure_budget
+        budget = llm_budget
+        yield(budget) if block_given?
+        budget.save!
+        budget
+      end
+
+      # Returns the budget status from BudgetTracker
+      #
+      # @return [Hash] Budget status
+      def llm_budget_status
+        BudgetTracker.status(tenant_id: llm_tenant_id)
+      end
+
+      # Checks if within budget for a given limit type
+      #
+      # @param type [Symbol] Limit type (:daily_cost, :monthly_cost, :daily_tokens, etc.)
+      # @return [Boolean] true if within budget
+      def llm_within_budget?(type: :daily_cost)
+        status = llm_budget_status
+        return true unless status[:enabled]
+
+        key = budget_status_key(type)
+        status.dig(key, :percentage_used).to_f < 100
+      end
+
+      # Returns remaining budget for a given limit type
+      #
+      # @param type [Symbol] Limit type
+      # @return [Numeric, nil] Remaining amount
+      def llm_remaining_budget(type: :daily_cost)
+        status = llm_budget_status
+        key = budget_status_key(type)
+        status.dig(key, :remaining)
+      end
+
+      # Raises an error if over budget
+      #
+      # @raise [BudgetExceededError] if budget is exceeded
+      # @return [void]
+      def llm_check_budget!
+        BudgetTracker.check_budget!(self.class.name, tenant_id: llm_tenant_id)
+      end
+
+      private
+
+      # Applies a period scope to an execution query
+      #
+      # @param scope [ActiveRecord::Relation] The query scope
+      # @param period [Symbol, Range] The period to filter by
+      # @return [ActiveRecord::Relation] Filtered scope
+      def apply_period_scope(scope, period)
+        case period
+        when :today then scope.where(created_at: Time.current.all_day)
+        when :yesterday then scope.where(created_at: 1.day.ago.all_day)
+        when :this_week then scope.where(created_at: Time.current.all_week)
+        when :this_month then scope.where(created_at: Time.current.all_month)
+        when Range then scope.where(created_at: period)
+        else scope
+        end
+      end
+
+      # Maps user-friendly type to budget status key
+      #
+      # @param type [Symbol] User-friendly type
+      # @return [Symbol] Status key
+      def budget_status_key(type)
+        case type
+        when :daily_cost then :global_daily
+        when :monthly_cost then :global_monthly
+        when :daily_tokens then :global_daily_tokens
+        when :monthly_tokens then :global_monthly_tokens
+        when :daily_executions then :global_daily_executions
+        when :monthly_executions then :global_monthly_executions
+        else :global_daily
+        end
+      end
+
+      # Creates the default budget on model creation
+      #
+      # @return [void]
+      def create_default_llm_budget
+        return if self.class.llm_tenant_options.blank?
+        return if llm_budget&.persisted?
+
+        options = self.class.llm_tenant_options
+        limits = options[:limits] || {}
+        name_method = options[:name] || :to_s
+
+        budget = build_llm_budget(
+          tenant_id: llm_tenant_id,
+          name: send(name_method).to_s,
+          daily_limit: limits[:daily_cost],
+          monthly_limit: limits[:monthly_cost],
+          daily_token_limit: limits[:daily_tokens],
+          monthly_token_limit: limits[:monthly_tokens],
+          daily_execution_limit: limits[:daily_executions],
+          monthly_execution_limit: limits[:monthly_executions],
+          enforcement: options[:enforcement]&.to_s || "soft",
+          inherit_global_defaults: options.fetch(:inherit_global, true)
+        )
+
+        budget.tenant_record = self
+        budget.save!
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/{version.rb → core/version.rb}

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "0.5.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/ruby_llm/agents/dsl/base.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module DSL
+      # Base DSL available to all agents.
+      #
+      # Provides common configuration methods that every agent type needs:
+      # - model: The LLM model to use
+      # - version: Cache invalidation version
+      # - description: Human-readable description
+      # - timeout: Request timeout
+      #
+      # @example Basic usage
+      #   class MyAgent < RubyLLM::Agents::BaseAgent
+      #     extend DSL::Base
+      #
+      #     model "gpt-4o"
+      #     version "2.0"
+      #     description "A helpful agent"
+      #   end
+      #
+      module Base
+        # @!group Configuration DSL
+
+        # Sets or returns the LLM model for this agent class
+        #
+        # @param value [String, nil] The model identifier to set
+        # @return [String] The current model setting
+        # @example
+        #   model "gpt-4o"
+        def model(value = nil)
+          @model = value if value
+          @model || inherited_or_default(:model, default_model)
+        end
+
+        # Sets or returns the version string for cache invalidation
+        #
+        # Change this when you want to invalidate cached results
+        # (e.g., after changing prompts or behavior).
+        #
+        # @param value [String, nil] Version string
+        # @return [String] The current version
+        # @example
+        #   version "2.0"
+        def version(value = nil)
+          @version = value if value
+          @version || inherited_or_default(:version, "1.0")
+        end
+
+        # Sets or returns the description for this agent class
+        #
+        # Useful for documentation and tool registration.
+        #
+        # @param value [String, nil] The description text
+        # @return [String, nil] The current description
+        # @example
+        #   description "Searches the knowledge base for relevant documents"
+        def description(value = nil)
+          @description = value if value
+          @description || inherited_or_default(:description, nil)
+        end
+
+        # Sets or returns the timeout in seconds for LLM requests
+        #
+        # @param value [Integer, nil] Timeout in seconds
+        # @return [Integer] The current timeout setting
+        # @example
+        #   timeout 30
+        def timeout(value = nil)
+          @timeout = value if value
+          @timeout || inherited_or_default(:timeout, default_timeout)
+        end
+
+        # @!endgroup
+
+        private
+
+        # Looks up setting from superclass or uses default
+        #
+        # @param method [Symbol] The method to call on superclass
+        # @param default [Object] Default value if not found
+        # @return [Object] The resolved value
+        def inherited_or_default(method, default)
+          return default unless superclass.respond_to?(method)
+
+          superclass.send(method)
+        end
+
+        # Returns the default model from configuration
+        #
+        # @return [String] The default model
+        def default_model
+          RubyLLM::Agents.configuration.default_model
+        rescue StandardError
+          "gpt-4o"
+        end
+
+        # Returns the default timeout from configuration
+        #
+        # @return [Integer] The default timeout
+        def default_timeout
+          RubyLLM::Agents.configuration.default_timeout
+        rescue StandardError
+          120
+        end
+      end
+    end
+  end
+end