ruby_llm 1.15.0 → 2.0.0.rc1

data/lib/ruby_llm/model/pricing.rb

@@ -1,43 +1,72 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  module Model
-    # A collection that manages and provides access to different categories of pricing information
+  class Model
+    # A Pricing groups a model's prices by usage category: text tokens,
+    # images, audio tokens, and embeddings. Each category is a
+    # PricingCategory. Prices are in USD per million tokens. Instances come
+    # from Model#pricing.
+    #
+    #   model = RubyLLM.models.find "claude-sonnet-5"
+    #   model.pricing.text_tokens.input   # => 3
+    #   model.pricing.text_tokens.output  # => 15
+    #
     class Pricing
-      def initialize(data)
+      # The pricing categories a model may define.
+      CATEGORIES = %i[text_tokens images audio_tokens embeddings].freeze
+
+      def initialize(data) # :nodoc:
         @data = {}
 
-        %i[text_tokens images audio_tokens embeddings].each do |category|
+        CATEGORIES.each do |category|
           @data[category] = PricingCategory.new(data[category]) if data[category] && !empty_pricing?(data[category])
         end
       end
 
-      def method_missing(method, *args)
-        if respond_to_missing?(method)
-          @data[method.to_sym] || PricingCategory.new
-        else
-          super
-        end
+      # Returns the PricingCategory for text token prices, or an empty
+      # category if the model has none.
+      def text_tokens
+        category(:text_tokens)
+      end
+
+      # Returns the PricingCategory for image generation prices, or an empty
+      # category if the model has none.
+      def images
+        category(:images)
       end
 
-      def respond_to_missing?(method, include_private = false)
-        %i[text_tokens images audio_tokens embeddings].include?(method.to_sym) || super
+      # Returns the PricingCategory for audio token prices, or an empty
+      # category if the model has none.
+      def audio_tokens
+        category(:audio_tokens)
       end
 
+      # Returns the PricingCategory for embedding prices, or an empty
+      # category if the model has none.
+      def embeddings
+        category(:embeddings)
+      end
+
+      # Returns the pricing data as a nested Hash keyed by category.
+      # Categories without prices are omitted.
       def to_h
         @data.transform_values(&:to_h)
       end
 
       private
 
+      def category(name)
+        @data[name] || PricingCategory.new
+      end
+
       def empty_pricing?(data)
         return true unless data
 
-        %i[standard batch].each do |tier|
+        PricingCategory::TIERS.each do |tier|
           next unless data[tier]
 
           data[tier].each_value do |value|
-            return false if value && value != 0.0
+            return false unless value.nil?
           end
         end
 

data/lib/ruby_llm/model/pricing_category.rb

@@ -1,56 +1,145 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  module Model
-    # Represents pricing tiers for different usage categories (standard and batch)
+  class Model
+    # A PricingCategory holds the standard, batch, and long-context pricing
+    # tiers for one kind of model usage, such as text tokens or images.
+    # Model#pricing returns a Pricing collection whose categories are
+    # PricingCategory instances. Prices are in USD per million tokens.
+    #
+    #   model    = RubyLLM.models.find "claude-sonnet-5"
+    #   category = model.pricing.text_tokens
+    #   category.input  # => 3
+    #   category.output # => 15
+    #
     class PricingCategory
-      attr_reader :standard, :batch
+      # The billing tiers a category may define.
+      TIERS = %i[standard batch long_context].freeze
 
-      def initialize(data = {})
-        @standard = PricingTier.new(data[:standard] || {}) unless empty_tier?(data[:standard])
-        @batch = PricingTier.new(data[:batch] || {}) unless empty_tier?(data[:batch])
+      # The standard-tier PricingTier, or +nil+ when the model has no
+      # standard pricing for this category.
+      attr_reader :standard
+
+      # The batch-tier PricingTier, or +nil+ when the model has no batch
+      # pricing for this category.
+      attr_reader :batch
+
+      # The long-context PricingTier, or +nil+ when the model has no
+      # separate rates for prompts above #long_context_threshold.
+      attr_reader :long_context
+
+      # Prompt-size threshold (in tokens) above which long-context rates
+      # apply, or +nil+ when the model has no long-context tier.
+      attr_reader :long_context_threshold
+
+      def initialize(data = {}) # :nodoc:
+        data = data.transform_keys(&:to_sym) if data.respond_to?(:transform_keys)
+
+        @standard = tier_from(data[:standard])
+        @batch = tier_from(data[:batch])
+        @long_context = tier_from(data[:long_context])
+        @long_context_threshold = Integer(data[:long_context_threshold], exception: false)
       end
 
+      # Returns the standard-tier input price in USD per million tokens,
+      # or +nil+ if the price is missing.
       def input
         standard&.input_per_million
       end
 
+      # Returns the standard-tier output price in USD per million tokens,
+      # or +nil+ if the price is missing.
       def output
         standard&.output_per_million
       end
 
+      # Returns the standard-tier cache read price in USD per million
+      # tokens, or +nil+ if the price is missing.
       def cache_read_input
-        standard&.cache_read_input_per_million || standard&.cached_input_per_million
+        standard&.cache_read_input_per_million
       end
 
+      # Returns the standard-tier cache write price in USD per million
+      # tokens, or +nil+ if the price is missing.
       def cache_write_input
-        standard&.cache_write_input_per_million || standard&.cache_creation_input_per_million
+        standard&.cache_write_input_per_million
       end
 
+      # Returns the standard-tier reasoning output price in USD per million
+      # tokens, or +nil+ if the price is missing.
       def reasoning_output
         standard&.reasoning_output_per_million
       end
 
-      alias cached_input cache_read_input
-      alias cache_creation_input cache_write_input
-
-      def [](key)
-        key == :batch ? batch : standard
+      # Returns the PricingTier that applies for a prompt of the given size.
+      # Uses #long_context when that tier exists and +prompt_tokens+ is
+      # greater than #long_context_threshold; otherwise returns #standard.
+      def tier_for(prompt_tokens)
+        if long_context && long_context_threshold &&
+           prompt_tokens.to_i > long_context_threshold
+          long_context
+        else
+          standard
+        end
       end
 
+      # Returns a Hash with present tier hashes and optional
+      # +:long_context_threshold+, omitting absent entries.
       def to_h
         result = {}
         result[:standard] = standard.to_h if standard
         result[:batch] = batch.to_h if batch
+        result[:long_context] = long_context.to_h if long_context
+        result[:long_context_threshold] = long_context_threshold if long_context_threshold
         result
       end
 
+      # Builds long-context rates and threshold from a models.dev-style cost
+      # Hash (as stored on Model#metadata under +:cost+). Returns
+      # <tt>[rates_hash, threshold]</tt>, or <tt>[nil, nil]</tt> when the
+      # cost has no context tier.
+      def self.long_context_from_cost(cost) # :nodoc:
+        cost = RubyLLM::Support::Utils.deep_symbolize_keys(cost || {})
+        return [nil, nil] if cost.empty?
+
+        entry, threshold = context_cost(cost)
+        return [nil, nil] unless entry
+
+        rates = {
+          input_per_million: entry[:input],
+          output_per_million: entry[:output],
+          cache_read_input_per_million: entry[:cache_read],
+          cache_write_input_per_million: entry[:cache_write],
+          reasoning_output_per_million: entry[:reasoning]
+        }.compact
+        rates.empty? ? [nil, nil] : [rates, threshold]
+      end
+
+      def self.context_cost(cost) # :nodoc:
+        context_tier = Array(cost[:tiers]).find do |entry|
+          entry.is_a?(Hash) && entry.dig(:tier, :type).to_s == 'context'
+        end
+        if context_tier
+          [context_tier, Integer(context_tier.dig(:tier, :size), exception: false)]
+        elsif cost[:context_over_200k].is_a?(Hash)
+          [cost[:context_over_200k], 200_000]
+        end
+      end
+
+      private_class_method :context_cost
+
       private
 
+      def tier_from(tier_data)
+        return nil if empty_tier?(tier_data)
+
+        PricingTier.new(tier_data || {})
+      end
+
       def empty_tier?(tier_data)
         return true unless tier_data
 
-        tier_data.values.all? { |v| v.nil? || v == 0.0 }
+        tier_data.values.all?(&:nil?)
       end
     end
   end

data/lib/ruby_llm/model/pricing_tier.rb

@@ -1,32 +1,83 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  module Model
-    # A dynamic class for storing non-zero pricing values with flexible attribute access
+  class Model
+    # A PricingTier holds the prices a model charges within one billing tier,
+    # such as standard, batch, or long_context. Each price is in USD per one
+    # million tokens. Prices missing from the registry read as +nil+. A zero
+    # price means the usage is free.
+    #
+    # Instances come from PricingCategory#standard, #batch, and #long_context:
+    #
+    #   model = RubyLLM.models.find "claude-sonnet-5"
+    #   tier  = model.pricing.text_tokens.standard
+    #   tier.input_per_million  # => 3
+    #   tier.output_per_million # => 15
+    #
     class PricingTier
-      def initialize(data = {})
+      # The names of the price readers a tier responds to.
+      ATTRIBUTES = %i[
+        input_per_million
+        output_per_million
+        cache_read_input_per_million
+        cache_write_input_per_million
+        reasoning_output_per_million
+      ].freeze
+
+      def initialize(data = {}) # :nodoc:
         @values = {}
 
         data.each do |key, value|
-          @values[key.to_sym] = value if value && value != 0.0
-        end
-      end
+          next if value.nil?
 
-      def method_missing(method, *args)
-        if method.to_s.end_with?('=')
-          key = method.to_s.chomp('=').to_sym
-          @values[key] = args.first if args.first && args.first != 0.0
-        elsif @values.key?(method)
-          @values[method]
+          @values[key.to_sym] = value
         end
       end
 
-      def respond_to_missing?(method, include_private = false)
-        method.to_s.end_with?('=') || @values.key?(method.to_sym) || super
+      ##
+      # :method: input_per_million
+      #
+      # Returns the USD price per million input tokens, or +nil+ if the
+      # price is missing.
+
+      ##
+      # :method: output_per_million
+      #
+      # Returns the USD price per million output tokens, or +nil+ if the
+      # price is missing.
+
+      ##
+      # :method: cache_read_input_per_million
+      #
+      # Returns the USD price per million input tokens read from the
+      # provider's prompt cache, or +nil+ if the price is missing.
+
+      ##
+      # :method: cache_write_input_per_million
+      #
+      # Returns the USD price per million input tokens written to the
+      # provider's prompt cache, or +nil+ if the price is missing.
+
+      ##
+      # :method: reasoning_output_per_million
+      #
+      # Returns the USD price per million reasoning output tokens, or +nil+
+      # if the price is missing.
+
+      ATTRIBUTES.each do |attribute|
+        define_method(attribute) do
+          @values[attribute]
+        end
       end
 
+      # Returns a new Hash of the tier's prices with Symbol keys. Missing
+      # prices are omitted.
+      #
+      #   tier.to_h
+      #   # => {input_per_million: 3, output_per_million: 15, ...}
+      #
       def to_h
-        @values
+        @values.dup
       end
     end
   end

data/lib/ruby_llm/model.rb

@@ -1,7 +1,249 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # Model-related classes for working with LLM models
-  module Model
+  # A Model describes one entry in the model registry: the model's identity,
+  # capabilities, modalities, pricing, and provider metadata. Instances come
+  # from the registry through RubyLLM.models and from Chat#model.
+  #
+  #   model = RubyLLM.models.find('gpt-5.6')
+  #   model.name              # => "GPT-5.6"
+  #   model.provider          # => "openai"
+  #   model.context_window    # => 1050000
+  #   model.supports?(:vision) # => true
+  #
+  class Model
+    include Support::Inspectable
+
+    # The provider's identifier for the model, e.g. <tt>"gpt-5.6"</tt>.
+    attr_reader :id
+
+    # The human-readable model name, e.g. <tt>"GPT-5.6"</tt>.
+    attr_reader :name
+
+    # The provider slug as a String, e.g. <tt>"openai"</tt>.
+    attr_reader :provider
+
+    # The model family as a String, e.g. <tt>"gpt"</tt>, or +nil+.
+    attr_reader :family
+
+    # The model's release timestamp as a UTC Time, or +nil+.
+    attr_reader :created_at
+
+    # The maximum number of input tokens the model accepts, or +nil+.
+    attr_reader :context_window
+
+    # The maximum number of tokens the model can generate, or +nil+.
+    attr_reader :max_output_tokens
+
+    # The model's training data cutoff as a Date, or +nil+.
+    attr_reader :knowledge_cutoff
+
+    # The supported input and output modalities as a Model::Modalities object.
+    #
+    #   model.modalities.input   # => ["text", "image", "pdf"]
+    #   model.modalities.output  # => ["text"]
+    #
+    attr_reader :modalities
+
+    # The model's capability names as an array of Strings,
+    # e.g. <tt>["function_calling", "streaming"]</tt>.
+    attr_reader :capabilities
+
+    # The model's pricing as a Model::Pricing object, in USD per million tokens.
+    attr_reader :pricing
+
+    # Provider-specific metadata as a Hash.
+    attr_reader :metadata
+
+    # The time the configured provider stopped listing the model, as a UTC
+    # Time, or +nil+ while the provider still lists it. Only a store that keeps
+    # unlisted entries, such as the Rails model table, sets it.
+    attr_reader :unlisted_at
+
+    attr_reader :reasoning_options # :nodoc:
+
+    def self.default(model_id, provider) # :nodoc:
+      new(
+        id: model_id,
+        name: model_id.tr('-', ' ').capitalize,
+        provider: provider,
+        capabilities: %w[function_calling streaming vision structured_output],
+        modalities: { input: %w[text image], output: %w[text] },
+        metadata: { warning: 'Assuming model exists, capabilities may not be accurate' }
+      )
+    end
+
+    def initialize(data) # :nodoc:
+      @id = data[:id]
+      @name = data[:name]
+      @provider = data[:provider]
+      @family = data[:family]
+      @created_at = Support::Utils.to_time(data[:created_at])&.utc
+      @context_window = data[:context_window]
+      @max_output_tokens = data[:max_output_tokens]
+      @knowledge_cutoff = Support::Utils.to_date(data[:knowledge_cutoff])
+      @modalities = Modalities.new(data[:modalities] || {})
+      @capabilities = data[:capabilities] || []
+      @metadata = data[:metadata]&.dup || {}
+      @unlisted_at = Support::Utils.to_time(data[:unlisted_at])&.utc
+      @pricing = Pricing.new(pricing_data_with_long_context(data[:pricing] || {}))
+      @reasoning_options = normalize_reasoning_options(reasoning_options_from(data))
+      store_reasoning_options_metadata
+    end
+
+    # Returns whether #capabilities includes +capability+, given as a String
+    # or Symbol.
+    #
+    #   model.supports?(:function_calling) # => true
+    #
+    def supports?(capability)
+      capabilities.include?(capability.to_s)
+    end
+
+    # Returns whether the configured provider has stopped listing the model.
+    # An unlisted model is kept only because application records still
+    # reference it, and it may already be failing at the provider.
+    #
+    #   model.unlisted? # => false
+    #
+    def unlisted?
+      !unlisted_at.nil?
+    end
+
+    # Returns the provider display name and model name combined,
+    # e.g. <tt>"OpenAI - GPT-5.6"</tt>.
+    def label
+      provider_name = provider_class&.display_name || provider
+      "#{provider_name} - #{name}"
+    end
+
+    def reasoning_option(type) # :nodoc:
+      reasoning_options.find { |option| option[:type] == type.to_s }
+    end
+
+    def reasoning_option_values(type) # :nodoc:
+      Array(reasoning_option(type)&.fetch(:values, nil))
+    end
+
+    # The standard text-token price columns, keyed by the symbol #price
+    # accepts.
+    PRICES = {
+      input: :input,
+      output: :output,
+      cache_read: :cache_read_input,
+      cache_write: :cache_write_input
+    }.freeze
+    private_constant :PRICES
+
+    # Returns the standard text-token price for +kind+ in USD per million
+    # tokens, or +nil+ if the registry has no such price. Valid kinds are
+    # +:input+, +:output+, +:cache_read+, and +:cache_write+.
+    #
+    #   model.price(:input)   # => 2.5
+    #   model.price(:output)  # => 10.0
+    #
+    def price(kind)
+      column = PRICES.fetch(kind) do
+        raise ArgumentError, "Unknown price kind: #{kind.inspect}. Valid kinds: #{PRICES.keys.join(', ')}"
+      end
+      pricing.text_tokens.public_send(column)
+    end
+
+    # Builds a Cost for +tokens+ (a Tokens object, or anything responding
+    # to +tokens+) using this model's pricing.
+    #
+    #   cost = model.cost_for(response.tokens)
+    #   puts cost.total
+    #
+    # Pass <tt>tier: :batch</tt> to use the model's explicit batch rates.
+    #
+    def cost_for(tokens, tier: :standard)
+      tokens = tokens.tokens if tokens.respond_to?(:tokens)
+
+      Cost.new(tokens:, model: self, tier:)
+    end
+
+    # Returns the Provider class registered for this model's provider slug,
+    # or +nil+ if no such provider is registered.
+    def provider_class
+      RubyLLM::Provider.resolve provider
+    end
+
+    # Returns the model's primary function, inferred from its output
+    # modalities: +:chat+, +:embedding+, +:moderation+, +:image+, +:audio+,
+    # +:video+, or +:rerank+.
+    def type
+      output = modalities.output
+      return :embedding if output.include?('embeddings')
+      return :moderation if output.include?('moderation')
+      return :image if output.include?('image')
+      return :audio if output.include?('audio')
+      return :video if output.include?('video')
+      return :rerank if output.include?('rerank')
+
+      :chat
+    end
+
+    def to_h # :nodoc:
+      data = {
+        id: id,
+        name: name,
+        provider: provider,
+        family: family,
+        created_at: created_at,
+        context_window: context_window,
+        max_output_tokens: max_output_tokens,
+        knowledge_cutoff: knowledge_cutoff,
+        modalities: modalities.to_h,
+        capabilities: capabilities,
+        pricing: pricing.to_h,
+        metadata: metadata
+      }
+      # A JSON registry drops unlisted models, so the key stays out of it.
+      data[:unlisted_at] = unlisted_at if unlisted_at
+      data
+    end
+
+    private
+
+    def pricing_data_with_long_context(pricing)
+      pricing = RubyLLM::Support::Utils.deep_symbolize_keys(RubyLLM::Support::Utils.deep_dup(pricing))
+      text = pricing[:text_tokens] || {}
+      return pricing if text[:long_context]
+
+      rates, threshold = PricingCategory.long_context_from_cost(metadata[:cost] || metadata['cost'])
+      return pricing unless rates
+
+      pricing[:text_tokens] = text.merge(long_context: rates)
+      pricing[:text_tokens][:long_context_threshold] = threshold if threshold
+      pricing
+    end
+
+    def reasoning_options_from(data)
+      data[:reasoning_options] || metadata[:reasoning_options] || metadata['reasoning_options']
+    end
+
+    def store_reasoning_options_metadata
+      return unless reasoning_options.any?
+
+      metadata.delete('reasoning_options')
+      metadata[:reasoning_options] = reasoning_options
+    end
+
+    def normalize_reasoning_options(options)
+      Array(options).filter_map do |option|
+        next unless option.is_a?(Hash)
+
+        normalized = option.to_h.transform_keys(&:to_sym)
+        normalized[:type] = normalized[:type].to_s if normalized[:type]
+        normalized[:values] = Array(normalized[:values]).map(&:to_s) if normalized.key?(:values)
+        normalized[:default] = normalized[:default].to_s if normalized[:default].is_a?(Symbol)
+        normalized
+      end
+    end
+
+    def inspect_attributes # :nodoc:
+      { id: id, provider: provider, name: name }
+    end
   end
 end

data/lib/ruby_llm/models/aliases.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  class Models
+    class Aliases # :nodoc:
+      class << self
+        def resolve(model_id, provider = nil)
+          return model_id unless aliases[model_id]
+
+          if provider
+            aliases[model_id][provider.to_s] || model_id
+          else
+            aliases[model_id].values.first || model_id
+          end
+        end
+
+        def aliases
+          @aliases ||= load_aliases
+        end
+
+        def aliases_file
+          File.expand_path('../aliases.json', __dir__)
+        end
+
+        def load_aliases
+          if File.exist?(aliases_file)
+            JSON.parse(File.read(aliases_file))
+          else
+            {}
+          end
+        end
+
+        def reload
+          @aliases = load_aliases
+        end
+      end
+    end
+  end
+end