ruby_llm-agents 1.1.0 → 1.2.0

data/app/models/ruby_llm/agents/tenant/trackable.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Tenant
+      # Tracks LLM usage for a tenant including costs, tokens, and execution counts.
+      #
+      # Provides methods for querying usage data with various time periods:
+      # - :today, :yesterday, :this_week, :last_week
+      # - :this_month, :last_month
+      # - Custom date ranges
+      #
+      # @example Querying costs
+      #   tenant.cost                    # Total cost all time
+      #   tenant.cost_today              # Today's cost
+      #   tenant.cost_this_month         # This month's cost
+      #   tenant.cost(period: 1.week.ago..Time.current)
+      #
+      # @example Usage summary
+      #   tenant.usage_summary
+      #   # => { tenant_id: "acme", cost: 123.45, tokens: 50000, executions: 100 }
+      #
+      # @example Usage breakdown
+      #   tenant.usage_by_agent
+      #   # => { "ChatAgent" => { cost: 50.0, tokens: 20000, count: 40 } }
+      #
+      # @see Execution
+      # @api public
+      module Trackable
+        extend ActiveSupport::Concern
+
+        included do
+          # Association to executions via tenant_id
+          has_many :executions,
+                   class_name: "RubyLLM::Agents::Execution",
+                   primary_key: :tenant_id,
+                   foreign_key: :tenant_id,
+                   inverse_of: false
+        end
+
+        # Cost queries
+
+        # Returns total cost for the given period
+        #
+        # @param period [Symbol, Range, nil] Time period (:today, :this_month, etc.) or date range
+        # @return [Float] Total cost in USD
+        def cost(period: nil)
+          scope = executions
+          scope = apply_period_scope(scope, period) if period
+          scope.sum(:total_cost) || 0
+        end
+
+        # Returns today's cost
+        #
+        # @return [Float]
+        def cost_today
+          cost(period: :today)
+        end
+
+        # Returns yesterday's cost
+        #
+        # @return [Float]
+        def cost_yesterday
+          cost(period: :yesterday)
+        end
+
+        # Returns this week's cost
+        #
+        # @return [Float]
+        def cost_this_week
+          cost(period: :this_week)
+        end
+
+        # Returns last week's cost
+        #
+        # @return [Float]
+        def cost_last_week
+          cost(period: :last_week)
+        end
+
+        # Returns this month's cost
+        #
+        # @return [Float]
+        def cost_this_month
+          cost(period: :this_month)
+        end
+
+        # Returns last month's cost
+        #
+        # @return [Float]
+        def cost_last_month
+          cost(period: :last_month)
+        end
+
+        # Token queries
+
+        # Returns total tokens for the given period
+        #
+        # @param period [Symbol, Range, nil] Time period or date range
+        # @return [Integer] Total tokens
+        def tokens(period: nil)
+          scope = executions
+          scope = apply_period_scope(scope, period) if period
+          scope.sum(:total_tokens) || 0
+        end
+
+        # Returns today's token usage
+        #
+        # @return [Integer]
+        def tokens_today
+          tokens(period: :today)
+        end
+
+        # Returns yesterday's token usage
+        #
+        # @return [Integer]
+        def tokens_yesterday
+          tokens(period: :yesterday)
+        end
+
+        # Returns this week's token usage
+        #
+        # @return [Integer]
+        def tokens_this_week
+          tokens(period: :this_week)
+        end
+
+        # Returns this month's token usage
+        #
+        # @return [Integer]
+        def tokens_this_month
+          tokens(period: :this_month)
+        end
+
+        # Returns last month's token usage
+        #
+        # @return [Integer]
+        def tokens_last_month
+          tokens(period: :last_month)
+        end
+
+        # Execution count queries
+
+        # Returns execution count for the given period
+        #
+        # @param period [Symbol, Range, nil] Time period or date range
+        # @return [Integer] Execution count
+        def execution_count(period: nil)
+          scope = executions
+          scope = apply_period_scope(scope, period) if period
+          scope.count
+        end
+
+        # Returns today's execution count
+        #
+        # @return [Integer]
+        def executions_today
+          execution_count(period: :today)
+        end
+
+        # Returns yesterday's execution count
+        #
+        # @return [Integer]
+        def executions_yesterday
+          execution_count(period: :yesterday)
+        end
+
+        # Returns this week's execution count
+        #
+        # @return [Integer]
+        def executions_this_week
+          execution_count(period: :this_week)
+        end
+
+        # Returns this month's execution count
+        #
+        # @return [Integer]
+        def executions_this_month
+          execution_count(period: :this_month)
+        end
+
+        # Returns last month's execution count
+        #
+        # @return [Integer]
+        def executions_last_month
+          execution_count(period: :last_month)
+        end
+
+        # Usage summaries
+
+        # Returns a complete usage summary for the tenant
+        #
+        # @param period [Symbol, Range] Time period (default: :this_month)
+        # @return [Hash] Usage summary
+        def usage_summary(period: :this_month)
+          {
+            tenant_id: tenant_id,
+            name: display_name,
+            period: period,
+            cost: cost(period: period),
+            tokens: tokens(period: period),
+            executions: execution_count(period: period)
+          }
+        end
+
+        # Returns usage broken down by agent type
+        #
+        # @param period [Symbol, Range] Time period (default: :this_month)
+        # @return [Hash] Usage by agent { "AgentName" => { cost:, tokens:, count: } }
+        def usage_by_agent(period: :this_month)
+          scope = executions
+          scope = apply_period_scope(scope, period) if period
+
+          scope.group(:agent_type).pluck(
+            :agent_type,
+            Arel.sql("SUM(total_cost)"),
+            Arel.sql("SUM(total_tokens)"),
+            Arel.sql("COUNT(*)")
+          ).to_h do |agent_type, total_cost, total_tokens, count|
+            [agent_type, { cost: total_cost || 0, tokens: total_tokens || 0, count: count }]
+          end
+        end
+
+        # Returns usage broken down by model
+        #
+        # @param period [Symbol, Range] Time period (default: :this_month)
+        # @return [Hash] Usage by model { "model-id" => { cost:, tokens:, count: } }
+        def usage_by_model(period: :this_month)
+          scope = executions
+          scope = apply_period_scope(scope, period) if period
+
+          scope.group(:model_id).pluck(
+            :model_id,
+            Arel.sql("SUM(total_cost)"),
+            Arel.sql("SUM(total_tokens)"),
+            Arel.sql("COUNT(*)")
+          ).to_h do |model_id, total_cost, total_tokens, count|
+            [model_id, { cost: total_cost || 0, tokens: total_tokens || 0, count: count }]
+          end
+        end
+
+        # Returns usage broken down by day for a given period
+        #
+        # @param period [Symbol, Range] Time period (default: :this_month)
+        # @return [Hash] Daily usage { Date => { cost:, tokens:, count: } }
+        def usage_by_day(period: :this_month)
+          scope = executions
+          scope = apply_period_scope(scope, period) if period
+
+          scope.group("DATE(created_at)").pluck(
+            Arel.sql("DATE(created_at)"),
+            Arel.sql("SUM(total_cost)"),
+            Arel.sql("SUM(total_tokens)"),
+            Arel.sql("COUNT(*)")
+          ).to_h do |date, total_cost, total_tokens, count|
+            [date.to_date, { cost: total_cost || 0, tokens: total_tokens || 0, count: count }]
+          end
+        end
+
+        # Returns the most recent executions for this tenant
+        #
+        # @param limit [Integer] Number of executions to return (default: 10)
+        # @return [Array<Execution>]
+        def recent_executions(limit: 10)
+          executions.order(created_at: :desc).limit(limit)
+        end
+
+        # Returns failed executions for this tenant
+        #
+        # @param period [Symbol, Range, nil] Time period
+        # @param limit [Integer, nil] Optional limit
+        # @return [ActiveRecord::Relation]
+        def failed_executions(period: nil, limit: nil)
+          scope = executions.where(status: "error")
+          scope = apply_period_scope(scope, period) if period
+          scope = scope.limit(limit) if limit
+          scope.order(created_at: :desc)
+        end
+
+        private
+
+        # Applies time period scope to a query
+        #
+        # @param scope [ActiveRecord::Relation]
+        # @param period [Symbol, Range]
+        # @return [ActiveRecord::Relation]
+        def apply_period_scope(scope, period)
+          case period
+          when :today
+            scope.where(created_at: Time.current.all_day)
+          when :yesterday
+            scope.where(created_at: 1.day.ago.all_day)
+          when :this_week
+            scope.where(created_at: Time.current.all_week)
+          when :last_week
+            scope.where(created_at: 1.week.ago.all_week)
+          when :this_month
+            scope.where(created_at: Time.current.all_month)
+          when :last_month
+            scope.where(created_at: 1.month.ago.all_month)
+          when Range
+            scope.where(created_at: period)
+          else
+            scope
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/ruby_llm/agents/tenant.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Central model for tenant management in multi-tenant LLM applications.
+    #
+    # Encapsulates all tenant-related functionality:
+    # - Budget limits and enforcement (via Budgetable concern)
+    # - Usage tracking: cost, tokens, executions (via Trackable concern)
+    # - API configuration per tenant (via Configurable concern)
+    #
+    # @example Creating a tenant
+    #   Tenant.create!(
+    #     tenant_id: "acme_corp",
+    #     name: "Acme Corporation",
+    #     daily_limit: 100.0,
+    #     enforcement: "hard"
+    #   )
+    #
+    # @example Linking to user's model
+    #   Tenant.create!(
+    #     tenant_id: organization.id.to_s,
+    #     tenant_record: organization,
+    #     daily_limit: 100.0
+    #   )
+    #
+    # @example Finding a tenant
+    #   tenant = Tenant.for(organization)
+    #   tenant = Tenant.for("acme_corp")
+    #
+    # @see Tenant::Budgetable
+    # @see Tenant::Trackable
+    # @see Tenant::Configurable
+    # @see LLMTenant
+    # @api public
+    class Tenant < ::ActiveRecord::Base
+      self.table_name = "ruby_llm_agents_tenants"
+
+      # Include concerns for organized functionality
+      include Tenant::Budgetable
+      include Tenant::Trackable
+      include Tenant::Configurable
+
+      # Polymorphic association to user's tenant model (optional)
+      # Allows linking to Organization, Account, or any ActiveRecord model
+      belongs_to :tenant_record, polymorphic: true, optional: true
+
+      # Validations
+      validates :tenant_id, presence: true, uniqueness: true
+
+      # Scopes
+      scope :active, -> { where(active: true) }
+      scope :inactive, -> { where(active: false) }
+      scope :linked, -> { where.not(tenant_record_type: nil) }
+      scope :unlinked, -> { where(tenant_record_type: nil) }
+
+      # Find tenant for given record or ID
+      #
+      # Supports multiple lookup strategies:
+      # 1. ActiveRecord model - looks up by polymorphic association first, then tenant_id
+      # 2. Object with llm_tenant_id - looks up by tenant_id
+      # 3. String - looks up by tenant_id
+      #
+      # @param tenant [String, ActiveRecord::Base, Object] Tenant ID, model, or object with llm_tenant_id
+      # @return [Tenant, nil] The tenant record or nil if not found
+      #
+      # @example Find by model
+      #   Tenant.for(organization)
+      #
+      # @example Find by string ID
+      #   Tenant.for("acme_corp")
+      #
+      def self.for(tenant)
+        return nil if tenant.blank?
+
+        if tenant.is_a?(::ActiveRecord::Base)
+          # ActiveRecord model - try polymorphic first, then tenant_id
+          find_by(tenant_record: tenant) ||
+            find_by(tenant_id: tenant.try(:llm_tenant_id) || tenant.id.to_s)
+        elsif tenant.respond_to?(:llm_tenant_id)
+          # Object with llm_tenant_id method
+          find_by(tenant_id: tenant.llm_tenant_id)
+        else
+          # String tenant_id
+          find_by(tenant_id: tenant.to_s)
+        end
+      end
+
+      # Find or create tenant
+      #
+      # @param tenant_id [String] Unique tenant identifier
+      # @param attributes [Hash] Additional attributes for creation
+      # @return [Tenant]
+      #
+      # @example
+      #   Tenant.for!("acme_corp", name: "Acme Corporation")
+      #
+      def self.for!(tenant_id, **attributes)
+        find_or_create_by!(tenant_id: tenant_id.to_s) do |tenant|
+          tenant.assign_attributes(attributes)
+        end
+      end
+
+      # Backward compatible class method aliases
+      class << self
+        alias_method :for_tenant, :for
+        alias_method :for_tenant!, :for!
+      end
+
+      # Display name (name or tenant_id fallback)
+      #
+      # @return [String]
+      def display_name
+        name.presence || tenant_id
+      end
+
+      # Check if tenant is linked to a user model
+      #
+      # @return [Boolean]
+      def linked?
+        tenant_record.present?
+      end
+
+      # Check if tenant is active
+      #
+      # @return [Boolean]
+      def active?
+        active != false
+      end
+
+      # Deactivate the tenant
+      #
+      # @return [Boolean]
+      def deactivate!
+        update!(active: false)
+      end
+
+      # Activate the tenant
+      #
+      # @return [Boolean]
+      def activate!
+        update!(active: true)
+      end
+    end
+  end
+end