ruby_llm-agents 3.7.2 → 3.9.0

data/lib/ruby_llm/agents/results/transcription_result.rb

@@ -26,6 +26,8 @@ module RubyLLM
     #
     # @api public
     class TranscriptionResult
+      include Trackable
+
       # @!group Content
 
       # @!attribute [r] text
@@ -250,6 +252,10 @@ module RubyLLM
 
         # Execution record
         @execution_id = attributes[:execution_id]
+
+        # Tracking
+        @agent_class_name = attributes[:agent_class_name]
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/text/embedder.rb

@@ -337,7 +337,14 @@ module RubyLLM
         embed_options = {model: context&.model || resolved_model}
         embed_options[:dimensions] = resolved_dimensions if resolved_dimensions
 
-        response = RubyLLM.embed(preprocessed, **embed_options)
+        # Use scoped RubyLLM::Context for thread-safe per-tenant API keys.
+        # RubyLLM::Context#embed creates an Embedding with the scoped config.
+        llm_ctx = context&.llm
+        response = if llm_ctx.is_a?(RubyLLM::Context)
+          llm_ctx.embed(preprocessed, **embed_options)
+        else
+          RubyLLM.embed(preprocessed, **embed_options)
+        end
 
         # ruby_llm returns vectors as an array (even for single text)
         vectors = response.vectors

data/lib/ruby_llm/agents/track_report.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Aggregated read-only report returned by RubyLLM::Agents.track.
+    #
+    # Provides totals and breakdowns across all agent calls made
+    # inside the tracked block.
+    #
+    # @example
+    #   report = RubyLLM::Agents.track do
+    #     TranscribeAgent.call(with: audio_path)
+    #     ChatAgent.call(message: "hello")
+    #   end
+    #   report.total_cost   # => 0.0078
+    #   report.call_count   # => 2
+    #
+    # @api public
+    class TrackReport
+      attr_reader :value, :error, :results, :request_id
+      attr_reader :started_at, :completed_at
+
+      def initialize(value:, error:, results:, request_id:, started_at:, completed_at:)
+        @value = value
+        @error = error
+        @results = results.freeze
+        @request_id = request_id
+        @started_at = started_at
+        @completed_at = completed_at
+      end
+
+      def successful?
+        @error.nil?
+      end
+
+      def failed?
+        !successful?
+      end
+
+      def call_count
+        @results.size
+      end
+
+      def total_cost
+        @results.sum { |r| r.total_cost || 0 }
+      end
+
+      def input_cost
+        @results.sum { |r| r.input_cost || 0 }
+      end
+
+      def output_cost
+        @results.sum { |r| r.output_cost || 0 }
+      end
+
+      def total_tokens
+        @results.sum { |r| r.total_tokens }
+      end
+
+      def input_tokens
+        @results.sum { |r| r.input_tokens || 0 }
+      end
+
+      def output_tokens
+        @results.sum { |r| r.output_tokens || 0 }
+      end
+
+      def duration_ms
+        return nil unless @started_at && @completed_at
+        ((@completed_at - @started_at) * 1000).to_i
+      end
+
+      def all_successful?
+        @results.all?(&:success?)
+      end
+
+      def any_errors?
+        @results.any?(&:error?)
+      end
+
+      def errors
+        @results.select(&:error?)
+      end
+
+      def successful
+        @results.select(&:success?)
+      end
+
+      def models_used
+        @results.filter_map(&:chosen_model_id).uniq
+      end
+
+      def cost_breakdown
+        @results.map do |r|
+          {
+            agent: r.respond_to?(:agent_class_name) ? r.agent_class_name : nil,
+            model: r.chosen_model_id,
+            cost: r.total_cost || 0,
+            tokens: r.total_tokens,
+            duration_ms: r.duration_ms
+          }
+        end
+      end
+
+      def to_h
+        {
+          successful: successful?,
+          value: value,
+          error: error&.message,
+          request_id: request_id,
+          call_count: call_count,
+          total_cost: total_cost,
+          input_cost: input_cost,
+          output_cost: output_cost,
+          total_tokens: total_tokens,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          duration_ms: duration_ms,
+          started_at: started_at,
+          completed_at: completed_at,
+          models_used: models_used,
+          cost_breakdown: cost_breakdown
+        }
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/tracker.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Internal collector used by RubyLLM::Agents.track to accumulate
+    # Result objects produced during a tracked block.
+    #
+    # Not part of the public API — users interact with TrackReport instead.
+    #
+    # @api private
+    class Tracker
+      attr_reader :results, :defaults, :request_id, :tags
+
+      def initialize(defaults: {}, request_id: nil, tags: {})
+        @results = []
+        @defaults = defaults
+        @request_id = request_id || generate_request_id
+        @tags = tags
+      end
+
+      def <<(result)
+        @results << result
+      end
+
+      private
+
+      def generate_request_id
+        "track_#{SecureRandom.hex(8)}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents.rb

@@ -37,7 +37,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"
@@ -78,6 +83,10 @@ require_relative "agents/image/pipeline"
 # Evaluation framework
 require_relative "agents/eval"
 
+# Providers (extends RubyLLM with additional providers)
+require_relative "agents/providers/inception"
+RubyLLM::Provider.register :inception, RubyLLM::Agents::Providers::Inception
+
 # Rails integration
 if defined?(Rails)
   require_relative "agents/core/inflections"
@@ -115,6 +124,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
@@ -144,6 +216,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.7.2
+  version: 3.9.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
@@ -120,6 +121,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 +140,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
@@ -154,6 +159,7 @@ files:
 - lib/generators/ruby_llm_agents/templates/add_assistant_prompt_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_attempts_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_caching_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/add_dashboard_performance_indexes_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_execution_type_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_finish_reason_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_prompts_migration.rb.tt
@@ -296,6 +302,12 @@ files:
 - lib/ruby_llm/agents/pricing/openrouter_adapter.rb
 - lib/ruby_llm/agents/pricing/portkey_adapter.rb
 - lib/ruby_llm/agents/pricing/ruby_llm_adapter.rb
+- lib/ruby_llm/agents/providers/inception.rb
+- lib/ruby_llm/agents/providers/inception/capabilities.rb
+- lib/ruby_llm/agents/providers/inception/chat.rb
+- lib/ruby_llm/agents/providers/inception/configuration.rb
+- lib/ruby_llm/agents/providers/inception/models.rb
+- lib/ruby_llm/agents/providers/inception/registry.rb
 - lib/ruby_llm/agents/rails/engine.rb
 - lib/ruby_llm/agents/results/background_removal_result.rb
 - lib/ruby_llm/agents/results/base.rb
@@ -308,11 +320,14 @@ 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/track_report.rb
+- lib/ruby_llm/agents/tracker.rb
 - lib/tasks/ruby_llm_agents.rake
 homepage: https://github.com/adham90/ruby_llm-agents
 licenses:
@@ -335,7 +350,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: []