ruby_llm-agents 3.8.0 → 3.10.0

data/lib/ruby_llm/agents.rb

@@ -26,6 +26,10 @@ require_relative "agents/base_agent"
 # Agent-as-Tool adapter
 require_relative "agents/agent_tool"
 
+# Tool base class and context for coding agents
+require_relative "agents/tool_context"
+require_relative "agents/tool"
+
 # Infrastructure - Budget & Utilities
 require_relative "agents/infrastructure/circuit_breaker"
 require_relative "agents/infrastructure/budget_tracker"
@@ -37,7 +41,12 @@ require_relative "agents/infrastructure/budget/config_resolver"
 require_relative "agents/infrastructure/budget/forecaster"
 require_relative "agents/infrastructure/budget/spend_recorder"
 
+# Tracking
+require_relative "agents/tracker"
+require_relative "agents/track_report"
+
 # Results
+require_relative "agents/results/trackable"
 require_relative "agents/results/base"
 require_relative "agents/results/embedding_result"
 require_relative "agents/results/transcription_result"
@@ -119,6 +128,69 @@ module RubyLLM
   # @see RubyLLM::Agents::Configuration
   module Agents
     class << self
+      # Wraps a block of agent calls, collecting all Results and
+      # returning an aggregated TrackReport.
+      #
+      # Shared options (tenant, tags, request_id) are injected into
+      # every agent instantiated inside the block unless overridden.
+      #
+      # @param tenant [Hash, Object, nil] Shared tenant for all calls
+      # @param request_id [String, nil] Shared request ID (auto-generated if nil)
+      # @param tags [Hash] Tags merged into each execution's metadata
+      # @param defaults [Hash] Additional shared options for agents
+      # @yield Block containing agent calls to track
+      # @return [TrackReport] Aggregated report of all calls
+      #
+      # @example Basic usage
+      #   report = RubyLLM::Agents.track do
+      #     ChatAgent.call(query: "hello")
+      #     SummaryAgent.call(text: "...")
+      #   end
+      #   report.total_cost  # => 0.015
+      #
+      # @example With shared tenant
+      #   report = RubyLLM::Agents.track(tenant: current_user) do
+      #     AgentA.call(query: "test")
+      #   end
+      def track(tenant: nil, request_id: nil, tags: {}, **defaults)
+        defaults[:tenant] = tenant if tenant
+        tracker = Tracker.new(defaults: defaults, request_id: request_id, tags: tags)
+
+        # Stack trackers for nesting support
+        previous_tracker = Thread.current[:ruby_llm_agents_tracker]
+        Thread.current[:ruby_llm_agents_tracker] = tracker
+
+        started_at = Time.current
+        value = nil
+        error = nil
+
+        begin
+          value = yield
+        rescue => e
+          error = e
+        end
+
+        completed_at = Time.current
+
+        report = TrackReport.new(
+          value: value,
+          error: error,
+          results: tracker.results,
+          request_id: tracker.request_id,
+          started_at: started_at,
+          completed_at: completed_at
+        )
+
+        # Bubble results up to parent tracker if nested
+        if previous_tracker
+          tracker.results.each { |r| previous_tracker << r }
+        end
+
+        report
+      ensure
+        Thread.current[:ruby_llm_agents_tracker] = previous_tracker
+      end
+
       # Returns the global configuration instance
       #
       # @return [Configuration] The configuration object
@@ -148,6 +220,146 @@ module RubyLLM
         @configuration = Configuration.new
       end
 
+      # ============================================================
+      # Convenience Query API
+      # ============================================================
+      # These methods provide quick access to execution data without
+      # needing to reference model classes directly.
+
+      # Returns a chainable scope of all executions.
+      #
+      # @return [ActiveRecord::Relation] All executions
+      #
+      # @example Recent successful executions
+      #   RubyLLM::Agents.executions.successful.recent(10)
+      #
+      # @example Filter by agent
+      #   RubyLLM::Agents.executions.by_agent("ChatAgent").today
+      def executions
+        Execution.all
+      end
+
+      # Returns a usage summary for a given period.
+      #
+      # @param period [Symbol, Range] :today, :yesterday, :this_week, :this_month,
+      #   :last_7_days, :last_30_days, or a custom Time range
+      # @param agent [String, Class, nil] Optional agent class or name to filter by
+      # @param tenant [String, Object, nil] Optional tenant ID or object to filter by
+      # @return [Hash] Usage summary with keys:
+      #   :executions, :successful, :failed, :success_rate,
+      #   :total_cost, :total_tokens, :avg_duration_ms, :avg_cost
+      #
+      # @example Global usage today
+      #   RubyLLM::Agents.usage(period: :today)
+      #
+      # @example Per-agent usage
+      #   RubyLLM::Agents.usage(period: :this_month, agent: "ChatAgent")
+      #
+      # @example Per-tenant usage
+      #   RubyLLM::Agents.usage(period: :this_week, tenant: current_user)
+      def usage(period: :today, agent: nil, tenant: nil)
+        scope = scope_for_period(Execution, period)
+        scope = scope.by_agent(agent_name_for(agent)) if agent
+        scope = scope_for_tenant(scope, tenant) if tenant
+
+        total = scope.count
+        successful = scope.successful.count
+
+        {
+          executions: total,
+          successful: successful,
+          failed: scope.failed.count,
+          success_rate: total.zero? ? 0.0 : (successful.to_f / total * 100).round(1),
+          total_cost: scope.sum(:total_cost),
+          total_tokens: scope.sum(:total_tokens),
+          avg_duration_ms: scope.average(:duration_ms)&.round,
+          avg_cost: total.zero? ? 0 : (scope.sum(:total_cost).to_f / total).round(6)
+        }
+      end
+
+      # Returns cost breakdown by agent for a period.
+      #
+      # @param period [Symbol, Range] Time period (see #usage)
+      # @param tenant [String, Object, nil] Optional tenant filter
+      # @return [Hash{String => Hash}] Agent name => { cost:, count:, avg_cost: }
+      #
+      # @example
+      #   RubyLLM::Agents.costs(period: :this_month)
+      #   # => { "ChatAgent" => { cost: 12.50, count: 1000, avg_cost: 0.0125 } }
+      def costs(period: :today, tenant: nil)
+        scope = scope_for_period(Execution, period)
+        scope = scope_for_tenant(scope, tenant) if tenant
+
+        scope.group(:agent_type).pluck(
+          :agent_type,
+          Arel.sql("COUNT(*)"),
+          Arel.sql("SUM(total_cost)"),
+          Arel.sql("AVG(total_cost)")
+        ).each_with_object({}) do |(agent, count, total, avg), hash|
+          hash[agent] = {
+            cost: total&.to_f&.round(6) || 0,
+            count: count,
+            avg_cost: avg&.to_f&.round(6) || 0
+          }
+        end
+      end
+
+      # Returns all registered agents with their stats.
+      #
+      # @return [Array<Hash>] Agent info with name, model, stats, etc.
+      #
+      # @example
+      #   RubyLLM::Agents.agents
+      #   # => [{ name: "ChatAgent", active: true, model: "gpt-4o", ... }]
+      def agents
+        AgentRegistry.all_with_details
+      end
+
+      # Returns a tenant's usage data.
+      #
+      # @param tenant [String, Object] Tenant ID or object with llm_tenant_id
+      # @return [RubyLLM::Agents::Tenant, nil] The tenant record
+      #
+      # @example
+      #   tenant = RubyLLM::Agents.tenant_for(current_user)
+      #   tenant.cost_today       # => 0.42
+      #   tenant.budget_status    # => { enabled: true, enforcement: :soft, ... }
+      def tenant_for(tenant)
+        Tenant.for(tenant)
+      rescue
+        nil
+      end
+
+      private
+
+      def scope_for_period(model, period)
+        case period
+        when :today then model.today
+        when :yesterday then model.yesterday
+        when :this_week then model.this_week
+        when :this_month then model.this_month
+        when :last_7_days then model.last_n_days(7)
+        when :last_30_days then model.last_n_days(30)
+        when Range then model.where(created_at: period)
+        else model.all
+        end
+      end
+
+      def scope_for_tenant(scope, tenant)
+        tenant_id = case tenant
+        when String then tenant
+        else
+          tenant.try(:llm_tenant_id) || tenant.try(:tenant_id) || tenant.try(:id)&.to_s
+        end
+        scope.by_tenant(tenant_id)
+      end
+
+      def agent_name_for(agent)
+        agent.is_a?(String) ? agent : agent.name
+      end
+
+      public
+
       # Renames an agent in the database, updating execution records and
       # tenant budget configuration keys
       #

data/lib/tasks/ruby_llm_agents.rake

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 namespace :ruby_llm_agents do
+  desc "Validate your RubyLLM::Agents setup (API keys, migrations, routes, jobs)"
+  task doctor: :environment do
+    require "generators/ruby_llm_agents/doctor_generator"
+    RubyLlmAgents::DoctorGenerator.start([])
+  end
+
   desc "Rename an agent type in execution records. Usage: rake ruby_llm_agents:rename_agent FROM=OldName TO=NewName [DRY_RUN=1]"
   task rename_agent: :environment do
     from = ENV["FROM"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.10.0
 platform: ruby
 authors:
 - adham90
@@ -82,6 +82,7 @@ files:
 - app/controllers/ruby_llm/agents/agents_controller.rb
 - app/controllers/ruby_llm/agents/dashboard_controller.rb
 - app/controllers/ruby_llm/agents/executions_controller.rb
+- app/controllers/ruby_llm/agents/requests_controller.rb
 - app/controllers/ruby_llm/agents/system_config_controller.rb
 - app/controllers/ruby_llm/agents/tenants_controller.rb
 - app/helpers/ruby_llm/agents/application_helper.rb
@@ -97,6 +98,7 @@ files:
 - app/models/ruby_llm/agents/tenant/resettable.rb
 - app/models/ruby_llm/agents/tenant/trackable.rb
 - app/models/ruby_llm/agents/tenant_budget.rb
+- app/models/ruby_llm/agents/tool_execution.rb
 - app/services/ruby_llm/agents/agent_registry.rb
 - app/views/layouts/ruby_llm/agents/application.html.erb
 - app/views/ruby_llm/agents/agents/_config_agent.html.erb
@@ -120,6 +122,8 @@ files:
 - app/views/ruby_llm/agents/executions/_list.html.erb
 - app/views/ruby_llm/agents/executions/index.html.erb
 - app/views/ruby_llm/agents/executions/show.html.erb
+- app/views/ruby_llm/agents/requests/index.html.erb
+- app/views/ruby_llm/agents/requests/show.html.erb
 - app/views/ruby_llm/agents/shared/_agent_type_badge.html.erb
 - app/views/ruby_llm/agents/shared/_doc_link.html.erb
 - app/views/ruby_llm/agents/shared/_executions_table.html.erb
@@ -137,6 +141,8 @@ files:
 - config/routes.rb
 - lib/generators/ruby_llm_agents/agent_generator.rb
 - lib/generators/ruby_llm_agents/background_remover_generator.rb
+- lib/generators/ruby_llm_agents/demo_generator.rb
+- lib/generators/ruby_llm_agents/doctor_generator.rb
 - lib/generators/ruby_llm_agents/embedder_generator.rb
 - lib/generators/ruby_llm_agents/image_analyzer_generator.rb
 - lib/generators/ruby_llm_agents/image_editor_generator.rb
@@ -315,11 +321,16 @@ files:
 - lib/ruby_llm/agents/results/image_upscale_result.rb
 - lib/ruby_llm/agents/results/image_variation_result.rb
 - lib/ruby_llm/agents/results/speech_result.rb
+- lib/ruby_llm/agents/results/trackable.rb
 - lib/ruby_llm/agents/results/transcription_result.rb
 - lib/ruby_llm/agents/routing.rb
 - lib/ruby_llm/agents/routing/class_methods.rb
 - lib/ruby_llm/agents/routing/result.rb
 - lib/ruby_llm/agents/text/embedder.rb
+- lib/ruby_llm/agents/tool.rb
+- lib/ruby_llm/agents/tool_context.rb
+- lib/ruby_llm/agents/track_report.rb
+- lib/ruby_llm/agents/tracker.rb
 - lib/tasks/ruby_llm_agents.rake
 homepage: https://github.com/adham90/ruby_llm-agents
 licenses:
@@ -342,7 +353,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.7
 specification_version: 4
 summary: Agent framework for building LLM-powered agents with RubyLLM
 test_files: []