ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/model/pricing_tier.rb

@@ -1,43 +1,83 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  module Model
-    # Stores non-zero pricing values for a single pricing tier.
+  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
+      # 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
-        cached_input_per_million
-        cache_creation_input_per_million
         reasoning_output_per_million
       ].freeze
 
-      def initialize(data = {})
+      def initialize(data = {}) # :nodoc:
         @values = {}
 
         data.each do |key, value|
-          @values[key.to_sym] = value if value && value != 0.0
+          next if value.nil?
+
+          @values[key.to_sym] = value
         end
       end
 
+      ##
+      # :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
-
-        define_method("#{attribute}=") do |value|
-          @values[attribute] = value if value && value != 0.0
-        end
-      end
-
-      def [](key)
-        @values[key.to_sym]
       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

data/lib/ruby_llm/models/registry.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'rbconfig'
+require 'tempfile'
+
+module RubyLLM
+  class Models
+    module Registry # :nodoc: all
+      PUBLISHED_URL = 'https://rubyllm.com/models.json'
+
+      class FileStore
+        attr_reader :path
+
+        def initialize(path)
+          @path = path.respond_to?(:path) ? path.path : path.to_s
+          raise ModelRegistryError, 'A model registry file path is required' if @path.empty?
+        end
+
+        def read
+          Registry.read(path)
+        end
+
+        def etag
+          return unless File.file?(path)
+
+          value = File.read(etag_path).strip
+          value unless value.empty?
+        rescue Errno::ENOENT
+          nil
+        rescue SystemCallError => e
+          raise ModelRegistryError, "Could not read the model registry ETag from #{etag_path}: #{e.message}"
+        end
+
+        def write(models, etag: nil)
+          FileUtils.mkdir_p(File.dirname(path))
+          atomic_write(path, Registry.pretty_json(models))
+          write_etag(etag)
+          models
+        end
+
+        private
+
+        def etag_path
+          "#{path}.etag"
+        end
+
+        def write_etag(etag)
+          if etag
+            atomic_write(etag_path, "#{etag}\n")
+          else
+            FileUtils.rm_f(etag_path)
+          end
+        end
+
+        def atomic_write(destination, contents)
+          directory = File.dirname(destination)
+          basename = File.basename(destination)
+          Tempfile.create([basename, '.tmp'], directory) do |temporary|
+            temporary.binmode
+            temporary.write(contents)
+            temporary.flush
+            temporary.fsync
+            temporary.chmod(readable_mode(destination))
+            replace_file(temporary.path, destination)
+          end
+        end
+
+        # Tempfile is 0600 and the rename carries that mode onto the registry,
+        # which then reads as unreadable to any other user on the machine.
+        def readable_mode(destination)
+          return File.stat(destination).mode & 0o7777 if File.exist?(destination)
+
+          0o666 & ~File.umask
+        end
+
+        def replace_file(source, destination)
+          File.rename(source, destination)
+        rescue Errno::EACCES, Errno::EEXIST
+          FileUtils.rm_f(destination)
+          File.rename(source, destination)
+        end
+      end
+
+      class PublishedSource
+        Result = Struct.new(:models, :etag, :not_modified)
+
+        attr_reader :url
+
+        def initialize(url = PUBLISHED_URL)
+          @url = url
+        end
+
+        def fetch(etag: nil)
+          connection = RubyLLM::Transport::Connection.basic do |faraday|
+            faraday.response :json, parser_options: { symbolize_names: true }
+          end
+          response = connection.get(url) do |request|
+            request.headers['If-None-Match'] = etag if etag
+          end
+
+          return Result.new(nil, response.headers['etag'] || etag, true) if response.status == 304
+
+          models = Registry.models_from_data(response.body, source: url)
+          raise ModelRegistryError, 'Published model registry is empty' if models.empty?
+
+          Result.new(models, response.headers['etag'], false)
+        rescue ModelRegistryError
+          raise
+        rescue StandardError => e
+          raise ModelRegistryError, "Could not refresh the model registry from #{url}: #{e.message}"
+        end
+      end
+
+      module_function
+
+      def read(file)
+        data = JSON.parse(File.read(file), symbolize_names: true)
+        models_from_data(data, source: file)
+      rescue Errno::ENOENT
+        nil
+      rescue JSON::ParserError => e
+        raise ModelRegistryError, "Invalid model registry JSON in #{file}: #{e.message}"
+      rescue SystemCallError => e
+        raise ModelRegistryError, "Could not read the model registry from #{file}: #{e.message}"
+      end
+
+      def models_from_data(data, source: nil)
+        unless data.is_a?(Array)
+          location = source ? " in #{source}" : ''
+          raise ModelRegistryError, "Model registry#{location} must be a JSON array"
+        end
+
+        data.map { |model| model.is_a?(RubyLLM::Model) ? model : RubyLLM::Model.new(model) }
+      end
+
+      def pretty_json(models)
+        "#{JSON.pretty_generate(Array(models).map(&:to_h))}\n"
+      end
+
+      def cache_path
+        home = Dir.home
+        host_os = RbConfig::CONFIG['host_os']
+
+        directory = if host_os.match?(/darwin/i)
+                      File.join(home, 'Library', 'Caches', 'RubyLLM')
+                    elsif host_os.match?(/mswin|mingw|cygwin/i)
+                      local_app_data = ENV.fetch('LOCALAPPDATA', nil)
+                      local_app_data = File.join(home, 'AppData', 'Local') if local_app_data.to_s.empty?
+                      File.join(local_app_data, 'RubyLLM', 'Cache')
+                    else
+                      xdg_cache = ENV.fetch('XDG_CACHE_HOME', nil)
+                      xdg_cache = File.join(home, '.cache') if xdg_cache.to_s.empty?
+                      File.join(xdg_cache, 'ruby_llm')
+                    end
+
+        File.join(directory, 'models.json')
+      rescue ArgumentError
+        # Dir.home raises when the home directory cannot be determined.
+        nil
+      end
+    end
+  end
+end

data/lib/ruby_llm/models/schema.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'schematist'
+
+module RubyLLM
+  class Models
+    # Validation schema for entries in the model registry. The registry
+    # builder validates refreshed registries against it before publishing,
+    # and the spec suite validates the bundled models.json.
+    class Schema < Schematist::Schema # :nodoc:
+      CAPABILITIES = %w[
+        streaming function_calling tool_choice parallel_tool_calls
+        structured_output predicted_outputs
+        distillation fine_tuning batch realtime image_generation
+        speech_generation transcription translation citations reasoning
+        caching moderation json_mode vision video ocr
+      ].freeze
+
+      description 'A model entry in the RubyLLM model registry'
+
+      string :id, description: 'Unique identifier for the model'
+      string :name, description: 'Display name of the model'
+      string :provider, description: 'Provider of the model (e.g., openai, anthropic, mistral)'
+
+      any_of :family, required: false, description: 'Model family (e.g., gpt-4, claude-3)' do
+        string
+        null
+      end
+
+      # Ruby Time#to_s strings today, not ISO8601; normalize at write time
+      # before tightening this to format: 'date-time'.
+      any_of :created_at, required: false, description: 'Creation date of the model' do
+        string
+        null
+      end
+
+      any_of :context_window, description: 'Maximum context window size' do
+        integer minimum: 0
+        null
+      end
+
+      any_of :max_output_tokens, description: 'Maximum output tokens' do
+        integer minimum: 0
+        null
+      end
+
+      any_of :knowledge_cutoff, required: false, description: 'Knowledge cutoff date' do
+        string format: 'date'
+        null
+      end
+
+      object :modalities, required: false do
+        array :input, description: 'Supported input modalities' do
+          string enum: RubyLLM::Models::MODELS_DEV_INPUT_MODALITIES
+        end
+        array :output, description: 'Supported output modalities' do
+          string enum: RubyLLM::Models::MODELS_DEV_OUTPUT_MODALITIES
+        end
+      end
+
+      array :capabilities, required: false, description: 'Model capabilities' do
+        string enum: CAPABILITIES
+      end
+
+      object :pricing, required: false, description: 'Pricing information for the model' do
+        RubyLLM::Model::Pricing::CATEGORIES.each do |category|
+          object category, required: false do
+            RubyLLM::Model::PricingCategory::TIERS.each do |tier|
+              object tier, required: false do
+                RubyLLM::Model::PricingTier::ATTRIBUTES.each do |attribute|
+                  number attribute, minimum: 0, required: false
+                end
+              end
+            end
+            integer :long_context_threshold,
+                    minimum: 0,
+                    required: false,
+                    description: 'Prompt size above which long_context rates apply'
+          end
+        end
+      end
+
+      object :metadata, required: false, description: 'Additional metadata about the model' do
+        additional_properties true
+      end
+
+      any_of :unlisted_at, required: false, description: 'When the provider stopped listing the model' do
+        string
+        null
+      end
+
+      # The Draft 2020-12 JSON Schema document for one model entry. Wrap it in an
+      # array schema to validate a whole registry.
+      def self.json_schema
+        new.to_json_schema
+      end
+    end
+  end
+end