ruby_llm-agents 3.7.2 → 3.9.0

data/lib/ruby_llm/agents/providers/inception/capabilities.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Providers
+      class Inception
+        # Determines capabilities and pricing for Inception Mercury models.
+        #
+        # Mercury models are diffusion LLMs with text-only I/O.
+        # Pricing is per million tokens.
+        #
+        # Models:
+        # - mercury-2: Reasoning dLLM, function calling, structured output
+        # - mercury: Base chat dLLM, function calling, structured output
+        # - mercury-coder-small: Fast coding model
+        # - mercury-edit: Code editing/FIM model
+        module Capabilities
+          module_function
+
+          REASONING_MODELS = %w[mercury-2].freeze
+          CODER_MODELS = %w[mercury-coder-small mercury-edit].freeze
+          FUNCTION_CALLING_MODELS = %w[mercury-2 mercury].freeze
+
+          def context_window_for(_model_id)
+            128_000
+          end
+
+          def max_tokens_for(_model_id)
+            32_000
+          end
+
+          def input_price_for(_model_id)
+            0.25
+          end
+
+          def output_price_for(model_id)
+            if CODER_MODELS.include?(model_id)
+              1.00
+            else
+              0.75
+            end
+          end
+
+          def supports_vision?(_model_id)
+            false
+          end
+
+          def supports_functions?(model_id)
+            FUNCTION_CALLING_MODELS.include?(model_id)
+          end
+
+          def supports_json_mode?(model_id)
+            FUNCTION_CALLING_MODELS.include?(model_id)
+          end
+
+          def format_display_name(model_id)
+            case model_id
+            when "mercury-2" then "Mercury 2"
+            when "mercury" then "Mercury"
+            when "mercury-coder-small" then "Mercury Coder Small"
+            when "mercury-edit" then "Mercury Edit"
+            else
+              model_id.split("-").map(&:capitalize).join(" ")
+            end
+          end
+
+          def model_type(model_id)
+            if CODER_MODELS.include?(model_id)
+              "code"
+            else
+              "chat"
+            end
+          end
+
+          def model_family(_model_id)
+            :mercury
+          end
+
+          def modalities_for(_model_id)
+            {input: ["text"], output: ["text"]}
+          end
+
+          def capabilities_for(model_id)
+            caps = ["streaming"]
+            if FUNCTION_CALLING_MODELS.include?(model_id)
+              caps << "function_calling"
+              caps << "structured_output"
+            end
+            caps << "reasoning" if REASONING_MODELS.include?(model_id)
+            caps
+          end
+
+          def pricing_for(model_id)
+            {
+              text_tokens: {
+                standard: {
+                  input_per_million: input_price_for(model_id),
+                  output_per_million: output_price_for(model_id)
+                }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/providers/inception/chat.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Providers
+      class Inception
+        # Chat methods for Inception Mercury API.
+        # Mercury uses standard OpenAI chat format.
+        module Chat
+          def format_role(role)
+            role.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/providers/inception/configuration.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Extends RubyLLM::Configuration with Inception API key support.
+# This allows users to configure: config.inception_api_key = ENV['INCEPTION_API_KEY']
+module RubyLLM
+  class Configuration
+    attr_accessor :inception_api_key unless method_defined?(:inception_api_key)
+  end
+end

data/lib/ruby_llm/agents/providers/inception/models.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Providers
+      class Inception
+        # Parses model metadata from the Inception /models API endpoint.
+        # Response format is OpenAI-compatible.
+        module Models
+          module_function
+
+          def parse_list_models_response(response, slug, capabilities)
+            Array(response.body["data"]).map do |model_data|
+              model_id = model_data["id"]
+
+              ::RubyLLM::Model::Info.new(
+                id: model_id,
+                name: capabilities.format_display_name(model_id),
+                provider: slug,
+                family: "mercury",
+                created_at: model_data["created"] ? Time.at(model_data["created"]) : nil,
+                context_window: capabilities.context_window_for(model_id),
+                max_output_tokens: capabilities.max_tokens_for(model_id),
+                modalities: capabilities.modalities_for(model_id),
+                capabilities: capabilities.capabilities_for(model_id),
+                pricing: capabilities.pricing_for(model_id),
+                metadata: {
+                  object: model_data["object"],
+                  owned_by: model_data["owned_by"]
+                }.compact
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/providers/inception/registry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Providers
+      class Inception
+        # Registers Mercury models in the RubyLLM model registry so they
+        # can be resolved by model ID without calling the Inception /models API.
+        module Registry
+          MODELS = [
+            {id: "mercury-2", name: "Mercury 2"},
+            {id: "mercury", name: "Mercury"},
+            {id: "mercury-coder-small", name: "Mercury Coder Small"},
+            {id: "mercury-edit", name: "Mercury Edit"}
+          ].freeze
+
+          module_function
+
+          def register_models!
+            models_instance = ::RubyLLM::Models.instance
+            capabilities = Inception::Capabilities
+
+            MODELS.each do |model_def|
+              model_id = model_def[:id]
+
+              model_info = ::RubyLLM::Model::Info.new(
+                id: model_id,
+                name: model_def[:name],
+                provider: "inception",
+                family: "mercury",
+                context_window: capabilities.context_window_for(model_id),
+                max_output_tokens: capabilities.max_tokens_for(model_id),
+                modalities: capabilities.modalities_for(model_id),
+                capabilities: capabilities.capabilities_for(model_id),
+                pricing: capabilities.pricing_for(model_id)
+              )
+
+              models_instance.all << model_info
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/providers/inception.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Configuration extension must be loaded first (adds inception_api_key to RubyLLM::Configuration)
+require_relative "inception/configuration"
+
+module RubyLLM
+  module Agents
+    module Providers
+      # Inception Labs Mercury API integration (OpenAI-compatible).
+      # Mercury models are diffusion LLMs (dLLMs) that generate tokens
+      # in parallel for dramatically faster inference.
+      #
+      # @see https://docs.inceptionlabs.ai/
+      class Inception < ::RubyLLM::Providers::OpenAI
+        def api_base
+          "https://api.inceptionlabs.ai/v1"
+        end
+
+        def headers
+          {
+            "Authorization" => "Bearer #{@config.inception_api_key}"
+          }
+        end
+
+        class << self
+          def capabilities
+            Inception::Capabilities
+          end
+
+          def configuration_requirements
+            %i[inception_api_key]
+          end
+        end
+      end
+    end
+  end
+end
+
+# Load sub-modules after the class is defined
+require_relative "inception/capabilities"
+require_relative "inception/chat"
+require_relative "inception/models"
+require_relative "inception/registry"
+
+# Include modules after they're loaded
+RubyLLM::Agents::Providers::Inception.include RubyLLM::Agents::Providers::Inception::Chat
+RubyLLM::Agents::Providers::Inception.include RubyLLM::Agents::Providers::Inception::Models
+
+# Register Mercury models in the RubyLLM model registry
+RubyLLM::Agents::Providers::Inception::Registry.register_models!

data/lib/ruby_llm/agents/rails/engine.rb

@@ -53,6 +53,17 @@ module RubyLLM
           helper RubyLLM::Agents::ApplicationHelper
           before_action :authenticate_dashboard!
 
+          rescue_from ::ActiveRecord::StatementInvalid do |e|
+            if e.message.include?("ruby_llm_agents_")
+              render plain: "RubyLLM::Agents migrations are pending.\n\n" \
+                           "Run: rails db:migrate\n" \
+                           "Or:  rails ruby_llm_agents:doctor",
+                status: :service_unavailable
+            else
+              raise
+            end
+          end
+
           private
 
           # Authenticates dashboard access using configured method

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

@@ -15,6 +15,8 @@ module RubyLLM
     #   result.success?   # => true
     #
     class BackgroundRemovalResult
+      include Trackable
+
       attr_reader :foreground, :mask, :source_image, :model_id, :output_format,
         :alpha_matting, :refine_edges,
         :started_at, :completed_at, :tenant_id, :remover_class,
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(foreground:, mask:, source_image:, model_id:, output_format:,
         alpha_matting:, refine_edges:, started_at:, completed_at:,
-        tenant_id:, remover_class:, error_class: nil, error_message: nil)
+        tenant_id:, remover_class:, error_class: nil, error_message: nil, agent_class_name: nil)
         @foreground = foreground
         @mask = mask
         @source_image = source_image
@@ -53,6 +55,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -107,6 +107,16 @@ module RubyLLM
       #   @return [Integer, nil] Database ID of the associated Execution record
       attr_reader :execution_id
 
+      # @!group Tracking
+      # @!attribute [r] agent_class_name
+      #   @return [String, nil] The agent class that produced this result
+      attr_reader :agent_class_name
+
+      # @!group Debug
+      # @!attribute [r] trace
+      #   @return [Array<Hash>, nil] Pipeline trace entries (when debug: true)
+      attr_reader :trace
+
       # Creates a new Result instance
       #
       # @param content [Hash, String] The processed response content
@@ -159,6 +169,16 @@ module RubyLLM
 
         # Execution record
         @execution_id = options[:execution_id]
+
+        # Tracking
+        @agent_class_name = options[:agent_class_name]
+
+        # Debug trace
+        @trace = options[:trace]
+
+        # Register with active tracker
+        tracker = Thread.current[:ruby_llm_agents_tracker]
+        tracker << self if tracker
       end
 
       # Loads the associated Execution record from the database
@@ -219,16 +239,18 @@ module RubyLLM
       # Returns whether tool calls were made during execution
       #
       # @return [Boolean] true if tool_calls_count > 0
-      def has_tool_calls?
+      def tool_calls?
         tool_calls_count.to_i > 0
       end
+      alias_method :has_tool_calls?, :tool_calls?
 
       # Returns whether thinking data is present in the result
       #
       # @return [Boolean] true if thinking_text is present
-      def has_thinking?
+      def thinking?
         thinking_text.present?
       end
+      alias_method :has_thinking?, :thinking?
 
       # Converts the result to a hash
       #
@@ -262,8 +284,10 @@ module RubyLLM
           thinking_text: thinking_text,
           thinking_signature: thinking_signature,
           thinking_tokens: thinking_tokens,
-          execution_id: execution_id
-        }
+          execution_id: execution_id,
+          agent_class_name: agent_class_name,
+          trace: trace
+        }.compact
       end
 
       # @!group Deprecated Hash Delegation

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

@@ -25,6 +25,8 @@ module RubyLLM
     #
     # @api public
     class EmbeddingResult
+      include Trackable
+
       # @!attribute [r] vectors
       #   @return [Array<Array<Float>>] The embedding vectors
       attr_reader :vectors
@@ -106,6 +108,8 @@ module RubyLLM
         @error_class = attributes[:error_class]
         @error_message = attributes[:error_message]
         @execution_id = attributes[:execution_id]
+        @agent_class_name = attributes[:agent_class_name]
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?     # => true
     #
     class ImageAnalysisResult
+      include Trackable
+
       attr_reader :image, :model_id, :analysis_type,
         :caption, :description, :tags, :objects, :colors, :text,
         :raw_response, :started_at, :completed_at, :tenant_id, :analyzer_class,
@@ -43,7 +45,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(image:, model_id:, analysis_type:, caption:, description:, tags:,
         objects:, colors:, text:, raw_response:, started_at:, completed_at:,
-        tenant_id:, analyzer_class:, error_class: nil, error_message: nil)
+        tenant_id:, analyzer_class:, error_class: nil, error_message: nil, agent_class_name: nil)
         @image = image
         @model_id = model_id
         @analysis_type = analysis_type
@@ -61,6 +63,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database
@@ -161,17 +167,19 @@ module RubyLLM
       #
       # @param name [String] Object name to search for
       # @return [Boolean] Whether the object was detected
-      def has_object?(name)
+      def includes_object?(name)
         objects.any? { |obj| obj[:name]&.downcase&.include?(name.to_s.downcase) }
       end
+      alias_method :has_object?, :includes_object?
 
       # Check if a specific tag is present
       #
       # @param tag [String] Tag to search for
       # @return [Boolean] Whether the tag is present
-      def has_tag?(tag)
+      def includes_tag?(tag)
         tags.any? { |t| t.downcase == tag.to_s.downcase }
       end
+      alias_method :has_tag?, :includes_tag?
 
       # Timing
 

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

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageEditResult
+      include Trackable
+
       attr_reader :images, :source_image, :mask, :prompt, :model_id, :size,
         :started_at, :completed_at, :tenant_id, :editor_class,
         :error_class, :error_message
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, source_image:, mask:, prompt:, model_id:, size:,
         started_at:, completed_at:, tenant_id:, editor_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @mask = mask
@@ -52,6 +54,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -20,6 +20,8 @@ module RubyLLM
     #   result.save_all("./logos")
     #
     class ImageGenerationResult
+      include Trackable
+
       attr_reader :images, :prompt, :model_id, :size, :quality, :style,
         :started_at, :completed_at, :tenant_id, :generator_class,
         :error_class, :error_message, :execution_id
@@ -40,7 +42,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, prompt:, model_id:, size:, quality:, style:,
         started_at:, completed_at:, tenant_id:, generator_class:,
-        error_class: nil, error_message: nil, execution_id: nil)
+        error_class: nil, error_message: nil, execution_id: nil, agent_class_name: nil)
         @images = images
         @prompt = prompt
         @model_id = model_id
@@ -54,6 +56,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = execution_id
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -21,6 +21,8 @@ module RubyLLM
     #   result.analysis          # => Shortcut to analyzer step result
     #
     class ImagePipelineResult
+      include Trackable
+
       attr_reader :step_results, :started_at, :completed_at, :tenant_id,
         :pipeline_class, :context, :error_class, :error_message
       attr_accessor :execution_id
@@ -36,7 +38,7 @@ module RubyLLM
       # @param error_class [String, nil] Error class name if failed
       # @param error_message [String, nil] Error message if failed
       def initialize(step_results:, started_at:, completed_at:, tenant_id:,
-        pipeline_class:, context:, error_class: nil, error_message: nil)
+        pipeline_class:, context:, error_class: nil, error_message: nil, agent_class_name: nil)
         @step_results = step_results
         @started_at = started_at
         @completed_at = completed_at
@@ -46,6 +48,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageTransformResult
+      include Trackable
+
       attr_reader :images, :source_image, :prompt, :model_id, :size, :strength,
         :started_at, :completed_at, :tenant_id, :transformer_class,
         :error_class, :error_message
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, source_image:, prompt:, model_id:, size:, strength:,
         started_at:, completed_at:, tenant_id:, transformer_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @prompt = prompt
@@ -52,6 +54,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -15,6 +15,8 @@ module RubyLLM
     #   result.success?     # => true
     #
     class ImageUpscaleResult
+      include Trackable
+
       attr_reader :image, :source_image, :model_id, :scale, :output_size, :face_enhance,
         :started_at, :completed_at, :tenant_id, :upscaler_class,
         :error_class, :error_message
@@ -36,7 +38,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(image:, source_image:, model_id:, scale:, output_size:, face_enhance:,
         started_at:, completed_at:, tenant_id:, upscaler_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @image = image
         @source_image = source_image
         @model_id = model_id
@@ -50,6 +52,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -14,6 +14,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageVariationResult
+      include Trackable
+
       attr_reader :images, :source_image, :model_id, :size, :variation_strength,
         :started_at, :completed_at, :tenant_id, :variator_class,
         :error_class, :error_message
@@ -34,7 +36,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, source_image:, model_id:, size:, variation_strength:,
         started_at:, completed_at:, tenant_id:, variator_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @model_id = model_id
@@ -47,6 +49,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -23,6 +23,8 @@ module RubyLLM
     #
     # @api public
     class SpeechResult
+      include Trackable
+
       # @!group Audio Content
 
       # @!attribute [r] audio
@@ -229,6 +231,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/results/trackable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Mixin that registers a result object with the active Tracker.
+    #
+    # Included in every result class so that RubyLLM::Agents.track
+    # can collect results automatically.
+    #
+    # @api private
+    module Trackable
+      def self.included(base)
+        base.attr_reader :agent_class_name unless base.method_defined?(:agent_class_name)
+      end
+
+      private
+
+      # Call from the end of initialize to register with the active tracker
+      def register_with_tracker
+        tracker = Thread.current[:ruby_llm_agents_tracker]
+        tracker << self if tracker
+      end
+    end
+  end
+end