ruby_llm 1.15.0 → 2.0.0.rc1

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