ruby_llm-agents 3.3.0 → 3.5.0

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

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module RubyLLM
+  module Agents
+    module Pricing
+      # Centralized HTTP fetch + two-layer cache for all pricing sources.
+      #
+      # Replaces the duplicated fetch_from_url / litellm_data / cache_expired?
+      # code previously copy-pasted across TranscriptionPricing, SpeechPricing,
+      # and ImageGenerator::Pricing.
+      #
+      # Two-layer cache:
+      #   Layer 1: In-memory (per-process, instant)
+      #   Layer 2: Rails.cache (cross-process, survives restarts)
+      #
+      # Thread-safety: All cache writes are protected by a Mutex.
+      #
+      # @example Fetch LiteLLM data
+      #   DataStore.litellm_data # => Hash of all models
+      #
+      # @example Fetch Portkey data for a specific model
+      #   DataStore.portkey_data("openai", "gpt-4o") # => Hash
+      #
+      # @example Refresh all caches
+      #   DataStore.refresh!
+      #
+      module DataStore
+        extend self
+
+        DEFAULT_CACHE_TTL = 24 * 60 * 60 # 24 hours
+
+        LITELLM_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+        OPENROUTER_URL = "https://openrouter.ai/api/v1/models"
+        HELICONE_URL = "https://www.helicone.ai/api/llm-costs"
+        PORTKEY_BASE_URL = "https://api.portkey.ai/model-configs/pricing"
+        LLMPRICING_BASE_URL = "https://llmpricing.ai/api"
+
+        # ============================================================
+        # Bulk fetchers (one HTTP call gets all models)
+        # ============================================================
+
+        # @return [Hash] model_id => { pricing fields }
+        def litellm_data
+          fetch_bulk(:litellm, litellm_url) { |body| JSON.parse(body) }
+        end
+
+        # @return [Array<Hash>] Array of model entries with pricing
+        def openrouter_data
+          return nil unless source_enabled?(:openrouter)
+
+          fetch_bulk(:openrouter, openrouter_url) do |body|
+            parsed = JSON.parse(body)
+            parsed.is_a?(Hash) ? (parsed["data"] || []) : parsed
+          end
+        end
+
+        # @return [Array<Hash>] Array of cost entries
+        def helicone_data
+          return nil unless source_enabled?(:helicone)
+
+          fetch_bulk(:helicone, helicone_url) do |body|
+            parsed = JSON.parse(body)
+            parsed.is_a?(Array) ? parsed : (parsed["data"] || parsed["costs"] || [])
+          end
+        end
+
+        # ============================================================
+        # Per-model fetchers (one HTTP call per model)
+        # ============================================================
+
+        # @param provider [String] e.g., "openai"
+        # @param model [String] e.g., "gpt-4o"
+        # @return [Hash, nil] Pricing data for this model
+        def portkey_data(provider, model)
+          return nil unless source_enabled?(:portkey)
+
+          cache_key = "portkey:#{provider}/#{model}"
+          fetch_per_model(cache_key, "#{portkey_base_url}/#{provider}/#{model}")
+        end
+
+        # @param provider [String] e.g., "OpenAI"
+        # @param model [String] e.g., "gpt-4o"
+        # @param input_tokens [Integer] Token count for cost calculation
+        # @param output_tokens [Integer] Token count for cost calculation
+        # @return [Hash, nil] Pricing data
+        def llmpricing_data(provider, model, input_tokens, output_tokens)
+          return nil unless source_enabled?(:llmpricing)
+
+          cache_key = "llmpricing:#{provider}/#{model}"
+          url = "#{llmpricing_base_url}/prices?provider=#{uri_encode(provider)}&model=#{uri_encode(model)}&input_tokens=#{input_tokens}&output_tokens=#{output_tokens}"
+          fetch_per_model(cache_key, url)
+        end
+
+        # ============================================================
+        # Cache management
+        # ============================================================
+
+        # Clear caches and optionally re-fetch
+        #
+        # @param source [Symbol] :all, :litellm, :openrouter, :helicone, :portkey, :llmpricing
+        def refresh!(source = :all)
+          mutex.synchronize do
+            case source
+            when :all
+              @bulk_cache = {}
+              @bulk_fetched_at = {}
+              @per_model_cache = {}
+              @per_model_fetched_at = {}
+            when :litellm, :openrouter, :helicone
+              @bulk_cache&.delete(source)
+              @bulk_fetched_at&.delete(source)
+            when :portkey
+              @per_model_cache&.reject! { |k, _| k.start_with?("portkey:") }
+              @per_model_fetched_at&.reject! { |k, _| k.start_with?("portkey:") }
+            when :llmpricing
+              @per_model_cache&.reject! { |k, _| k.start_with?("llmpricing:") }
+              @per_model_fetched_at&.reject! { |k, _| k.start_with?("llmpricing:") }
+            end
+          end
+        end
+
+        # @return [Hash] Cache statistics for each source
+        def cache_stats
+          {
+            litellm: bulk_stats(:litellm),
+            openrouter: bulk_stats(:openrouter),
+            helicone: bulk_stats(:helicone),
+            portkey: per_model_stats("portkey:"),
+            llmpricing: per_model_stats("llmpricing:")
+          }
+        end
+
+        private
+
+        def mutex
+          @mutex ||= Mutex.new
+        end
+
+        # ============================================================
+        # Bulk fetch with two-layer cache
+        # ============================================================
+
+        def fetch_bulk(source, url, &parser)
+          @bulk_cache ||= {}
+          @bulk_fetched_at ||= {}
+
+          # Layer 1: In-memory
+          if @bulk_cache[source] && !bulk_cache_expired?(source)
+            return @bulk_cache[source]
+          end
+
+          # Layer 2: Rails.cache
+          data = from_rails_cache("ruby_llm_agents:pricing:#{source}") do
+            raw_fetch(url, &parser)
+          end
+
+          mutex.synchronize do
+            @bulk_cache[source] = data
+            @bulk_fetched_at[source] = Time.now
+          end
+
+          data
+        rescue => e
+          warn "[RubyLLM::Agents::Pricing] Failed to fetch #{source}: #{e.message}"
+          mutex.synchronize { @bulk_cache[source] = nil }
+          nil
+        end
+
+        # ============================================================
+        # Per-model fetch with two-layer cache
+        # ============================================================
+
+        def fetch_per_model(cache_key, url)
+          @per_model_cache ||= {}
+          @per_model_fetched_at ||= {}
+
+          # Layer 1: In-memory
+          if @per_model_cache.key?(cache_key) && !per_model_cache_expired?(cache_key)
+            return @per_model_cache[cache_key]
+          end
+
+          # Layer 2: Rails.cache
+          data = from_rails_cache("ruby_llm_agents:pricing:#{cache_key}") do
+            raw_fetch(url) { |body| JSON.parse(body) }
+          end
+
+          mutex.synchronize do
+            @per_model_cache[cache_key] = data
+            @per_model_fetched_at[cache_key] = Time.now
+          end
+
+          data
+        rescue => e
+          warn "[RubyLLM::Agents::Pricing] Failed to fetch #{cache_key}: #{e.message}"
+          nil
+        end
+
+        # ============================================================
+        # HTTP fetch
+        # ============================================================
+
+        def raw_fetch(url)
+          uri = URI(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = 5
+          http.read_timeout = 15
+
+          request = Net::HTTP::Get.new(uri)
+          request["Accept"] = "application/json"
+          response = http.request(request)
+
+          return nil unless response.is_a?(Net::HTTPSuccess)
+
+          if block_given?
+            yield response.body
+          else
+            JSON.parse(response.body)
+          end
+        rescue => e
+          warn "[RubyLLM::Agents::Pricing] HTTP error: #{e.message}"
+          nil
+        end
+
+        # ============================================================
+        # Rails.cache layer
+        # ============================================================
+
+        def from_rails_cache(key)
+          if rails_cache_available?
+            Rails.cache.fetch(key, expires_in: cache_ttl) { yield }
+          else
+            yield
+          end
+        end
+
+        def rails_cache_available?
+          defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache
+        end
+
+        # ============================================================
+        # Cache expiration
+        # ============================================================
+
+        def bulk_cache_expired?(source)
+          fetched_at = @bulk_fetched_at&.dig(source)
+          return true unless fetched_at
+          Time.now - fetched_at > cache_ttl
+        end
+
+        def per_model_cache_expired?(cache_key)
+          fetched_at = @per_model_fetched_at&.dig(cache_key)
+          return true unless fetched_at
+          Time.now - fetched_at > cache_ttl
+        end
+
+        def cache_ttl
+          cfg = config
+          ttl = cfg.respond_to?(:pricing_cache_ttl) && cfg.pricing_cache_ttl
+          ttl ||= cfg.respond_to?(:litellm_pricing_cache_ttl) && cfg.litellm_pricing_cache_ttl
+          return DEFAULT_CACHE_TTL unless ttl
+          ttl.respond_to?(:to_i) ? ttl.to_i : DEFAULT_CACHE_TTL
+        end
+
+        # ============================================================
+        # URL helpers
+        # ============================================================
+
+        def litellm_url
+          cfg = config
+          (cfg.respond_to?(:litellm_pricing_url) && cfg.litellm_pricing_url) || LITELLM_URL
+        end
+
+        def openrouter_url
+          cfg = config
+          (cfg.respond_to?(:openrouter_pricing_url) && cfg.openrouter_pricing_url) || OPENROUTER_URL
+        end
+
+        def helicone_url
+          cfg = config
+          (cfg.respond_to?(:helicone_pricing_url) && cfg.helicone_pricing_url) || HELICONE_URL
+        end
+
+        def portkey_base_url
+          cfg = config
+          (cfg.respond_to?(:portkey_pricing_url) && cfg.portkey_pricing_url) || PORTKEY_BASE_URL
+        end
+
+        def llmpricing_base_url
+          cfg = config
+          (cfg.respond_to?(:llmpricing_url) && cfg.llmpricing_url) || LLMPRICING_BASE_URL
+        end
+
+        def source_enabled?(source)
+          cfg = config
+          method_name = :"#{source}_pricing_enabled"
+          return true unless cfg.respond_to?(method_name)
+          cfg.send(method_name) != false
+        end
+
+        def uri_encode(str)
+          URI.encode_www_form_component(str.to_s)
+        end
+
+        # ============================================================
+        # Stats helpers
+        # ============================================================
+
+        def bulk_stats(source)
+          data = @bulk_cache&.dig(source)
+          {
+            fetched_at: @bulk_fetched_at&.dig(source),
+            size: if data.is_a?(Hash)
+                    data.size
+                  else
+                    (data.is_a?(Array) ? data.size : 0)
+                  end,
+            cached: !data.nil?
+          }
+        end
+
+        def per_model_stats(prefix)
+          entries = (@per_model_cache || {}).select { |k, _| k.start_with?(prefix) }
+          {
+            cached_models: entries.size,
+            keys: entries.keys
+          }
+        end
+
+        def config
+          RubyLLM::Agents.configuration
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pricing
+      # Normalizes Helicone bulk cost list into the common pricing format.
+      #
+      # Helicone prices are **per 1M tokens**. This adapter converts to
+      # per-token for consistency.
+      #
+      # Coverage: 172 text LLM models, some realtime audio models.
+      # No transcription, TTS, image, or embedding models.
+      #
+      # @example
+      #   HeliconeAdapter.find_model("gpt-4o")
+      #   # => { input_cost_per_token: 0.0000025, output_cost_per_token: 0.00001, source: :helicone }
+      #
+      module HeliconeAdapter
+        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)
+          data = DataStore.helicone_data
+          return nil unless data.is_a?(Array) && data.any?
+
+          entry = find_matching(data, model_id)
+          return nil unless entry
+
+          normalize(entry)
+        end
+
+        private
+
+        def find_matching(data, model_id)
+          normalized = model_id.to_s.downcase
+
+          # Exact match on model field
+          entry = data.find { |e| e["model"]&.downcase == normalized }
+          return entry if entry
+
+          # Try without provider prefix
+          entry = data.find do |e|
+            model_name = e["model"].to_s.downcase
+            model_name == normalized || model_name.end_with?("/#{normalized}")
+          end
+          return entry if entry
+
+          # Fuzzy: model field contains the normalized ID
+          data.find do |e|
+            e["model"].to_s.downcase.include?(normalized)
+          end
+        end
+
+        def normalize(entry)
+          result = {source: :helicone}
+
+          # Per-1M-token → per-token
+          if (input_1m = safe_number(entry["input_cost_per_1m"]))
+            result[:input_cost_per_token] = input_1m / 1_000_000.0
+          end
+
+          if (output_1m = safe_number(entry["output_cost_per_1m"]))
+            result[:output_cost_per_token] = output_1m / 1_000_000.0
+          end
+
+          # Audio tokens (realtime models)
+          if (audio_in = safe_number(entry["prompt_audio_per_1m"]))
+            result[:input_cost_per_audio_token] = audio_in / 1_000_000.0
+          end
+
+          if (audio_out = safe_number(entry["completion_audio_per_1m"]))
+            result[:output_cost_per_audio_token] = audio_out / 1_000_000.0
+          end
+
+          (result.keys.size > 1) ? result : nil
+        end
+
+        def safe_number(value)
+          return nil unless value.is_a?(Numeric) && value.positive?
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pricing
+      # Normalizes LiteLLM bulk JSON into the common pricing format.
+      #
+      # Supports all model types:
+      # - Text LLM: input_cost_per_token, output_cost_per_token
+      # - Transcription: input_cost_per_second, input_cost_per_audio_token
+      # - TTS/Speech: input_cost_per_character, output_cost_per_character
+      # - Image: input_cost_per_image, input_cost_per_pixel
+      # - Embedding: input_cost_per_token (with mode: "embedding")
+      #
+      # @example
+      #   LiteLLMAdapter.find_model("whisper-1")
+      #   # => { input_cost_per_second: 0.0001, mode: "audio_transcription", source: :litellm }
+      #
+      module LiteLLMAdapter
+        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)
+          data = DataStore.litellm_data
+          return nil unless data.is_a?(Hash) && data.any?
+
+          model_data = find_by_candidates(data, model_id)
+          return nil unless model_data
+
+          normalize(model_data)
+        end
+
+        private
+
+        def find_by_candidates(data, model_id)
+          normalized = normalize_model_id(model_id)
+
+          # Exact and prefix candidate keys
+          candidates = [
+            model_id,
+            normalized,
+            "audio_transcription/#{model_id}",
+            "tts/#{model_id}",
+            "openai/#{model_id}",
+            "elevenlabs/#{model_id}",
+            "whisper/#{model_id}"
+          ]
+
+          candidates.each do |key|
+            return data[key] if data[key].is_a?(Hash)
+          end
+
+          # Fuzzy match: find keys containing the normalized model ID
+          normalized_lower = normalized.downcase
+          data.each do |key, value|
+            next unless value.is_a?(Hash)
+            key_lower = key.to_s.downcase
+
+            if key_lower.include?(normalized_lower) || normalized_lower.include?(key_lower.split("/").last.to_s)
+              return value
+            end
+          end
+
+          nil
+        end
+
+        def normalize(raw)
+          result = {source: :litellm}
+
+          # Text LLM / Embedding
+          result[:input_cost_per_token] = raw["input_cost_per_token"] if raw["input_cost_per_token"]
+          result[:output_cost_per_token] = raw["output_cost_per_token"] if raw["output_cost_per_token"]
+
+          # Transcription
+          result[:input_cost_per_second] = raw["input_cost_per_second"] if raw["input_cost_per_second"]
+          result[:input_cost_per_audio_token] = raw["input_cost_per_audio_token"] if raw["input_cost_per_audio_token"]
+
+          # TTS / Speech
+          result[:input_cost_per_character] = raw["input_cost_per_character"] if raw["input_cost_per_character"]
+          result[:output_cost_per_character] = raw["output_cost_per_character"] if raw["output_cost_per_character"]
+          result[:output_cost_per_audio_token] = raw["output_cost_per_audio_token"] if raw["output_cost_per_audio_token"]
+
+          # Image
+          result[:input_cost_per_image] = raw["input_cost_per_image"] if raw["input_cost_per_image"]
+          result[:input_cost_per_pixel] = raw["input_cost_per_pixel"] if raw["input_cost_per_pixel"]
+          result[:input_cost_per_image_hd] = raw["input_cost_per_image_hd"] if raw["input_cost_per_image_hd"]
+
+          # Metadata
+          result[:mode] = raw["mode"] if raw["mode"]
+
+          result
+        end
+
+        def normalize_model_id(model_id)
+          model_id.to_s.downcase
+            .gsub(/[^a-z0-9._\/-]/, "-").squeeze("-")
+            .gsub(/^-|-$/, "")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pricing
+      # Normalizes LLM Pricing AI per-model data into the common pricing format.
+      #
+      # This API returns **calculated costs** for a given token count, not raw rates.
+      # We query with 1M tokens to derive per-token rates.
+      #
+      # Coverage: ~79 models across 4 providers (OpenAI, Anthropic, Groq, Mistral).
+      # Text LLM only — no transcription, TTS, image, or embedding.
+      #
+      # @example
+      #   LLMPricingAdapter.find_model("gpt-4o")
+      #   # => { input_cost_per_token: 0.0000025, output_cost_per_token: 0.00001, source: :llmpricing }
+      #
+      module LLMPricingAdapter
+        extend self
+
+        PROVIDER_MAP = [
+          [/^(gpt-|o1|o3|o4|whisper|dall-e|tts-|chatgpt)/, "OpenAI"],
+          [/^claude/, "Anthropic"],
+          [/^(mixtral|mistral|codestral|pixtral|ministral)/, "Mistral"],
+          [/^(gemma|llama)/, "Groq"]
+        ].freeze
+
+        QUERY_TOKENS = 1_000_000
+
+        # 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 = resolve_provider(model_id)
+          return nil unless provider
+
+          raw = DataStore.llmpricing_data(provider, model_id, QUERY_TOKENS, QUERY_TOKENS)
+          return nil unless raw.is_a?(Hash)
+          return nil unless raw["input_cost"].is_a?(Numeric) && raw["input_cost"].positive?
+
+          normalize(raw)
+        end
+
+        private
+
+        def resolve_provider(model_id)
+          id = model_id.to_s.downcase
+
+          PROVIDER_MAP.each do |pattern, provider|
+            return provider if id.match?(pattern)
+          end
+
+          nil
+        end
+
+        def normalize(raw)
+          result = {source: :llmpricing}
+
+          if raw["input_cost"].is_a?(Numeric)
+            result[:input_cost_per_token] = raw["input_cost"] / QUERY_TOKENS.to_f
+          end
+
+          if raw["output_cost"].is_a?(Numeric) && raw["output_cost"].positive?
+            result[:output_cost_per_token] = raw["output_cost"] / QUERY_TOKENS.to_f
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

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