ruby_llm-agents 3.4.0 → 3.5.1

data/lib/ruby_llm/agents/pricing/openrouter_adapter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pricing
+      # Normalizes OpenRouter bulk model list into the common pricing format.
+      #
+      # OpenRouter prices are **strings** representing USD per token.
+      # This adapter converts them to Float.
+      #
+      # Coverage: 400+ text LLM models, some audio-capable chat models.
+      # No transcription, image generation, or embedding models.
+      #
+      # @example
+      #   OpenRouterAdapter.find_model("openai/gpt-4o")
+      #   # => { input_cost_per_token: 0.0000025, output_cost_per_token: 0.00001, source: :openrouter }
+      #
+      module OpenRouterAdapter
+        extend self
+
+        # Find and normalize pricing for a model
+        #
+        # @param model_id [String] The model identifier
+        # @return [Hash, nil] Normalized pricing hash or nil
+        def find_model(model_id)
+          models = DataStore.openrouter_data
+          return nil unless models.is_a?(Array) && models.any?
+
+          entry = find_by_id(models, model_id)
+          return nil unless entry
+
+          normalize(entry)
+        end
+
+        private
+
+        def find_by_id(models, model_id)
+          normalized = model_id.to_s.downcase
+
+          # Exact match by id field
+          entry = models.find { |m| m["id"]&.downcase == normalized }
+          return entry if entry
+
+          # Try without provider prefix (e.g., "gpt-4o" matches "openai/gpt-4o")
+          entry = models.find do |m|
+            id = m["id"].to_s.downcase
+            id.end_with?("/#{normalized}") || id == normalized
+          end
+          return entry if entry
+
+          # Try with common provider prefixes
+          prefixes = %w[openai anthropic google meta-llama mistralai cohere deepseek]
+          prefixes.each do |prefix|
+            entry = models.find { |m| m["id"]&.downcase == "#{prefix}/#{normalized}" }
+            return entry if entry
+          end
+
+          nil
+        end
+
+        def normalize(entry)
+          pricing = entry["pricing"]
+          return nil unless pricing.is_a?(Hash)
+
+          result = {source: :openrouter}
+
+          prompt_cost = safe_float(pricing["prompt"])
+          completion_cost = safe_float(pricing["completion"])
+
+          result[:input_cost_per_token] = prompt_cost if prompt_cost&.positive?
+          result[:output_cost_per_token] = completion_cost if completion_cost&.positive?
+
+          if pricing["image"]
+            image_cost = safe_float(pricing["image"])
+            result[:image_cost_raw] = image_cost if image_cost&.positive?
+          end
+
+          (result.keys.size > 1) ? result : nil
+        end
+
+        def safe_float(value)
+          return nil if value.nil?
+          Float(value)
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/pricing/portkey_adapter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pricing
+      # Normalizes Portkey AI per-model pricing into the common format.
+      #
+      # Portkey prices are in **cents per token**. This adapter converts to
+      # USD per token for consistency with other adapters.
+      #
+      # Requires knowing the provider for a model, resolved via PROVIDER_MAP.
+      #
+      # @example
+      #   PortkeyAdapter.find_model("gpt-4o")
+      #   # => { input_cost_per_token: 0.0000025, output_cost_per_token: 0.00001, source: :portkey }
+      #
+      module PortkeyAdapter
+        extend self
+
+        PROVIDER_MAP = [
+          [/^(gpt-|o1|o3|o4|whisper|dall-e|tts-|chatgpt)/, "openai"],
+          [/^claude/, "anthropic"],
+          [/^gemini/, "google"],
+          [/^(mistral|codestral|pixtral|ministral)/, "mistralai"],
+          [/^llama/, "meta"],
+          [/^(command|embed)/, "cohere"],
+          [/^deepseek/, "deepseek"],
+          [/^(nova|titan)/, "amazon"]
+        ].freeze
+
+        # Find and normalize pricing for a model
+        #
+        # @param model_id [String] The model identifier
+        # @return [Hash, nil] Normalized pricing hash or nil
+        def find_model(model_id)
+          provider, model_name = resolve_provider(model_id)
+          return nil unless provider
+
+          raw = DataStore.portkey_data(provider, model_name)
+          return nil unless raw.is_a?(Hash) && raw["pay_as_you_go"]
+
+          normalize(raw)
+        end
+
+        private
+
+        def resolve_provider(model_id)
+          id = model_id.to_s
+
+          # Handle prefixed model IDs like "azure/gpt-4o" or "groq/llama-3"
+          if id.include?("/")
+            parts = id.split("/", 2)
+            return [parts[0], parts[1]]
+          end
+
+          PROVIDER_MAP.each do |pattern, provider|
+            return [provider, id] if id.match?(pattern)
+          end
+
+          nil
+        end
+
+        def normalize(raw)
+          pag = raw["pay_as_you_go"]
+          return nil unless pag
+
+          result = {source: :portkey}
+
+          # Main text token pricing (cents → USD)
+          req_price = dig_price(pag, "request_token", "price")
+          resp_price = dig_price(pag, "response_token", "price")
+          result[:input_cost_per_token] = req_price / 100.0 if req_price&.positive?
+          result[:output_cost_per_token] = resp_price / 100.0 if resp_price&.positive?
+
+          # Additional units (audio tokens, etc.)
+          additional = pag["additional_units"]
+          if additional.is_a?(Hash)
+            audio_in = dig_price(additional, "request_audio_token", "price")
+            audio_out = dig_price(additional, "response_audio_token", "price")
+            result[:input_cost_per_audio_token] = audio_in / 100.0 if audio_in&.positive?
+            result[:output_cost_per_audio_token] = audio_out / 100.0 if audio_out&.positive?
+          end
+
+          (result.keys.size > 1) ? result : nil
+        end
+
+        def dig_price(hash, *keys)
+          value = hash.dig(*keys)
+          value.is_a?(Numeric) ? value : nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/pricing/ruby_llm_adapter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pricing
+      # Extracts pricing from the ruby_llm gem's built-in model registry.
+      #
+      # This is a local, zero-HTTP-cost source that provides pricing for
+      # models that ruby_llm knows about. It's the fastest adapter since
+      # all data is already loaded in-process.
+      #
+      # Uses RubyLLM::Models.find(model_id) which returns pricing as
+      # USD per million tokens.
+      #
+      # @example
+      #   RubyLLMAdapter.find_model("gpt-4o")
+      #   # => { input_cost_per_token: 0.0000025, output_cost_per_token: 0.00001, source: :ruby_llm }
+      #
+      module RubyLLMAdapter
+        extend self
+
+        # Find and normalize pricing for a model from ruby_llm's registry
+        #
+        # @param model_id [String] The model identifier
+        # @return [Hash, nil] Normalized pricing hash or nil
+        def find_model(model_id)
+          return nil unless defined?(::RubyLLM::Models)
+
+          model_info = ::RubyLLM::Models.find(model_id)
+          return nil unless model_info
+
+          normalize(model_info)
+        rescue
+          nil
+        end
+
+        private
+
+        def normalize(model_info)
+          pricing = model_info.pricing
+          return nil unless pricing
+
+          result = {source: :ruby_llm}
+
+          # Text tokens (per million → per token)
+          text_tokens = pricing.respond_to?(:text_tokens) ? pricing.text_tokens : nil
+          if text_tokens
+            input_per_million = text_tokens.respond_to?(:input) ? text_tokens.input : nil
+            output_per_million = text_tokens.respond_to?(:output) ? text_tokens.output : nil
+
+            if input_per_million.is_a?(Numeric) && input_per_million.positive?
+              result[:input_cost_per_token] = input_per_million / 1_000_000.0
+            end
+
+            if output_per_million.is_a?(Numeric) && output_per_million.positive?
+              result[:output_cost_per_token] = output_per_million / 1_000_000.0
+            end
+          end
+
+          # Audio tokens (per million → per token) if available
+          audio_tokens = pricing.respond_to?(:audio_tokens) ? pricing.audio_tokens : nil
+          if audio_tokens
+            audio_input = audio_tokens.respond_to?(:input) ? audio_tokens.input : nil
+            audio_output = audio_tokens.respond_to?(:output) ? audio_tokens.output : nil
+
+            if audio_input.is_a?(Numeric) && audio_input.positive?
+              result[:input_cost_per_audio_token] = audio_input / 1_000_000.0
+            end
+
+            if audio_output.is_a?(Numeric) && audio_output.positive?
+              result[:output_cost_per_audio_token] = audio_output / 1_000_000.0
+            end
+          end
+
+          # Image pricing if available
+          images = pricing.respond_to?(:images) ? pricing.images : nil
+          if images
+            per_image = images.respond_to?(:input) ? images.input : nil
+            if per_image.is_a?(Numeric) && per_image.positive?
+              result[:input_cost_per_image] = per_image
+            end
+          end
+
+          # Mode from model type if available
+          if model_info.respond_to?(:type)
+            result[:mode] = model_info.type.to_s
+          end
+
+          (result.keys.size > 1) ? result : nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/routing/class_methods.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Routing
+      # Class-level DSL for defining routes and classification categories.
+      #
+      # Extended into any BaseAgent subclass that includes the Routing concern.
+      # Provides `route`, `default_route`, and accessor methods for route definitions.
+      #
+      # @example
+      #   class SupportRouter < RubyLLM::Agents::BaseAgent
+      #     include RubyLLM::Agents::Routing
+      #
+      #     route :billing,  "Billing, charges, refunds"
+      #     route :technical, "Bugs, errors, crashes"
+      #     default_route :general
+      #   end
+      #
+      module ClassMethods
+        # Define a classification route.
+        #
+        # @param name [Symbol] Route identifier
+        # @param description [String] What messages belong to this route
+        # @param agent [Class, nil] Optional agent class to map to this route
+        #
+        # @example Simple route
+        #   route :billing, "Billing, charges, refunds"
+        #
+        # @example Route with agent mapping
+        #   route :billing, "Billing questions", agent: BillingAgent
+        #
+        def route(name, description, agent: nil)
+          @routes ||= {}
+          @routes[name.to_sym] = {
+            description: description,
+            agent: agent
+          }
+        end
+
+        # Set the default route for unmatched classifications.
+        #
+        # @param name [Symbol] Default route name
+        # @param agent [Class, nil] Optional default agent class
+        #
+        def default_route(name, agent: nil)
+          @default_route_name = name.to_sym
+          @routes ||= {}
+          @routes[name.to_sym] ||= {
+            description: "Default / general category",
+            agent: agent
+          }
+        end
+
+        # Returns all defined routes (including inherited).
+        #
+        # @return [Hash{Symbol => Hash}] Route definitions
+        def routes
+          parent = superclass.respond_to?(:routes) ? superclass.routes : {}
+          parent.merge(@routes || {})
+        end
+
+        # Returns the default route name (including inherited).
+        #
+        # @return [Symbol] The default route name
+        def default_route_name
+          @default_route_name || (superclass.respond_to?(:default_route_name) ? superclass.default_route_name : :general)
+        end
+
+        # Returns :router for instrumentation/tracking.
+        #
+        # @return [Symbol]
+        def agent_type
+          :router
+        end
+
+        # Override call to accept message: as a named param.
+        #
+        # @param message [String, nil] The message to classify
+        # @param kwargs [Hash] Additional options
+        # @return [RoutingResult] The classification result
+        def call(message: nil, **kwargs, &block)
+          if message
+            super(**kwargs.merge(message: message), &block)
+          else
+            super(**kwargs, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/routing/result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Routing
+      # Wraps a standard Result with routing-specific accessors.
+      #
+      # Delegates all standard Result methods (tokens, cost, timing, etc.)
+      # to the underlying result, adding only the route-specific interface.
+      #
+      # @example
+      #   result = SupportRouter.call(message: "I was charged twice")
+      #   result.route        # => :billing
+      #   result.agent_class  # => BillingAgent (if mapped)
+      #   result.success?     # => true
+      #   result.total_cost   # => 0.0001
+      #
+      class RoutingResult < Result
+        # @return [Symbol] The classified route name
+        attr_reader :route
+
+        # @return [Class, nil] The mapped agent class (if defined via `agent:`)
+        attr_reader :agent_class
+
+        # @return [String] The raw text response from the LLM
+        attr_reader :raw_response
+
+        # Creates a new RoutingResult by wrapping a base Result with route data.
+        #
+        # @param base_result [Result] The standard Result from BaseAgent execution
+        # @param route_data [Hash] Parsed route information
+        # @option route_data [Symbol] :route The classified route name
+        # @option route_data [Class, nil] :agent_class Mapped agent class
+        # @option route_data [String] :raw_response Raw LLM text
+        def initialize(base_result:, route_data:)
+          super(
+            content: route_data,
+            input_tokens: base_result.input_tokens,
+            output_tokens: base_result.output_tokens,
+            input_cost: base_result.input_cost,
+            output_cost: base_result.output_cost,
+            total_cost: base_result.total_cost,
+            model_id: base_result.model_id,
+            chosen_model_id: base_result.chosen_model_id,
+            temperature: base_result.temperature,
+            started_at: base_result.started_at,
+            completed_at: base_result.completed_at,
+            duration_ms: base_result.duration_ms,
+            finish_reason: base_result.finish_reason,
+            streaming: base_result.streaming,
+            error_class: base_result.error_class,
+            error_message: base_result.error_message,
+            attempts_count: base_result.attempts_count
+          )
+
+          @route = route_data[:route]
+          @agent_class = route_data[:agent_class]
+          @raw_response = route_data[:raw_response]
+        end
+
+        # Converts the result to a hash including routing fields.
+        #
+        # @return [Hash] All result data plus route, agent_class, raw_response
+        def to_h
+          super.merge(
+            route: route,
+            agent_class: agent_class&.name,
+            raw_response: raw_response
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/routing.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "routing/class_methods"
+require_relative "routing/result"
+
+module RubyLLM
+  module Agents
+    # Adds classification & routing capabilities to any BaseAgent.
+    #
+    # Include this module in a BaseAgent subclass to get:
+    # - `route` DSL for defining classification categories
+    # - `default_route` for fallback classification
+    # - Auto-generated system/user prompts from route definitions
+    # - Structured output parsing to return a RoutingResult
+    #
+    # All existing BaseAgent features (caching, reliability, retries,
+    # fallback models, instrumentation, multi-tenancy) work unchanged.
+    #
+    # @example Class-based router
+    #   class SupportRouter < RubyLLM::Agents::BaseAgent
+    #     include RubyLLM::Agents::Routing
+    #
+    #     model "gpt-4o-mini"
+    #     temperature 0.0
+    #
+    #     route :billing,  "Billing, charges, refunds"
+    #     route :technical, "Bugs, errors, crashes"
+    #     default_route :general
+    #   end
+    #
+    #   result = SupportRouter.call(message: "I was charged twice")
+    #   result.route  # => :billing
+    #
+    # @example Inline classification
+    #   route = RubyLLM::Agents::Routing.classify(
+    #     message: "I was charged twice",
+    #     routes: { billing: "Billing issues", technical: "Tech issues" },
+    #     default: :general
+    #   )
+    #   # => :billing
+    #
+    module Routing
+      def self.included(base)
+        unless base < BaseAgent
+          raise ArgumentError, "#{base} must inherit from RubyLLM::Agents::BaseAgent to include Routing"
+        end
+
+        base.extend(ClassMethods)
+        base.param(:message, required: false)
+      end
+
+      # Classify a message without defining a router class.
+      #
+      # Creates an anonymous BaseAgent subclass with Routing included,
+      # calls it, and returns just the route symbol.
+      #
+      # @param message [String] The message to classify
+      # @param routes [Hash{Symbol => String}] Route names to descriptions
+      # @param default [Symbol] Default route (:general)
+      # @param model [String] LLM model to use ("gpt-4o-mini")
+      # @param options [Hash] Extra options passed to .call
+      # @return [Symbol] The classified route name
+      def self.classify(message:, routes:, default: :general, model: "gpt-4o-mini", **options)
+        router_model = model
+        router = Class.new(BaseAgent) do
+          include Routing
+
+          self.model router_model
+          temperature 0.0
+
+          routes.each do |name, desc|
+            route name, desc
+          end
+          default_route default
+        end
+
+        result = router.call(message: message, **options)
+        result.route
+      end
+
+      # Helper to get the auto-generated system prompt for routing.
+      # Use this in custom system_prompt overrides to include route definitions.
+      #
+      # @return [String] The auto-generated routing system prompt
+      def routing_system_prompt
+        default = self.class.default_route_name
+
+        <<~PROMPT.strip
+          You are a message classifier. Classify the user's message into exactly one of the following categories:
+
+          #{routing_categories_text}
+
+          If none of the categories clearly match, classify as: #{default}
+
+          Respond with ONLY the category name, nothing else.
+        PROMPT
+      end
+
+      # Helper to get formatted route categories for use in custom prompts.
+      #
+      # @return [String] Formatted list of route categories
+      def routing_categories_text
+        self.class.routes.map do |name, config|
+          "- #{name}: #{config[:description]}"
+        end.join("\n")
+      end
+
+      # Auto-generated system_prompt (used if subclass doesn't override).
+      def system_prompt
+        super || routing_system_prompt
+      end
+
+      # Auto-generated user_prompt from the :message param.
+      def user_prompt
+        @ask_message || options[:message] || super
+      end
+
+      # Override process_response to parse the route from LLM output.
+      def process_response(response)
+        raw = response.content.to_s.strip.downcase.gsub(/[^a-z0-9_]/, "")
+        route_name = raw.to_sym
+
+        valid_routes = self.class.routes.keys
+        route_name = self.class.default_route_name unless valid_routes.include?(route_name)
+
+        {
+          route: route_name,
+          agent_class: self.class.routes.dig(route_name, :agent),
+          raw_response: response.content.to_s.strip
+        }
+      end
+
+      # Override build_result to return a RoutingResult.
+      def build_result(content, response, context)
+        base = super
+        RoutingResult.new(base_result: base, route_data: content)
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents.rb

@@ -57,6 +57,9 @@ require_relative "agents/results/image_pipeline_result"
 require_relative "agents/image/concerns/image_operation_dsl"
 require_relative "agents/image/concerns/image_operation_execution"
 
+# Routing concern (classification & routing)
+require_relative "agents/routing"
+
 # Text agents
 require_relative "agents/text/embedder"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.1
 platform: ruby
 authors:
 - adham90
@@ -102,6 +102,7 @@ files:
 - app/views/ruby_llm/agents/agents/_config_embedder.html.erb
 - app/views/ruby_llm/agents/agents/_config_image_generator.html.erb
 - app/views/ruby_llm/agents/agents/_config_moderator.html.erb
+- app/views/ruby_llm/agents/agents/_config_router.html.erb
 - app/views/ruby_llm/agents/agents/_config_speaker.html.erb
 - app/views/ruby_llm/agents/agents/_config_transcriber.html.erb
 - app/views/ruby_llm/agents/agents/_empty_state.html.erb
@@ -215,6 +216,7 @@ files:
 - lib/ruby_llm/agents/audio/speech_client.rb
 - lib/ruby_llm/agents/audio/speech_pricing.rb
 - lib/ruby_llm/agents/audio/transcriber.rb
+- lib/ruby_llm/agents/audio/transcription_pricing.rb
 - lib/ruby_llm/agents/base_agent.rb
 - lib/ruby_llm/agents/core/base.rb
 - lib/ruby_llm/agents/core/base/callbacks.rb
@@ -282,6 +284,13 @@ files:
 - lib/ruby_llm/agents/pipeline/middleware/instrumentation.rb
 - lib/ruby_llm/agents/pipeline/middleware/reliability.rb
 - lib/ruby_llm/agents/pipeline/middleware/tenant.rb
+- lib/ruby_llm/agents/pricing/data_store.rb
+- lib/ruby_llm/agents/pricing/helicone_adapter.rb
+- lib/ruby_llm/agents/pricing/litellm_adapter.rb
+- lib/ruby_llm/agents/pricing/llmpricing_adapter.rb
+- 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/rails/engine.rb
 - lib/ruby_llm/agents/results/background_removal_result.rb
 - lib/ruby_llm/agents/results/base.rb
@@ -295,6 +304,9 @@ files:
 - lib/ruby_llm/agents/results/image_variation_result.rb
 - lib/ruby_llm/agents/results/speech_result.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/tasks/ruby_llm_agents.rake
 homepage: https://github.com/adham90/ruby_llm-agents