ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/providers/ollama.rb

@@ -3,10 +3,15 @@
 module RubyLLM
   module Providers
     # Ollama API integration.
-    class Ollama < OpenAI
-      include Ollama::Chat
-      include Ollama::Media
-      include Ollama::Models
+    class Ollama < Provider
+      # Ollama's dialect of the Chat Completions API.
+      class ChatCompletions < Protocols::ChatCompletions
+        include Ollama::Chat
+        include Ollama::Media
+        include Ollama::Models
+      end
+
+      protocol :chat_completions, ChatCompletions
 
       def api_base
         @config.ollama_api_base
@@ -30,10 +35,6 @@ module RubyLLM
         def local?
           true
         end
-
-        def capabilities
-          Ollama::Capabilities
-        end
       end
     end
   end

data/lib/ruby_llm/providers/ollama_cloud/models.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OllamaCloud
+      # Models methods for the Ollama Cloud API integration
+      module Models
+        def model_capabilities
+          super - %w[structured_output]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/ollama_cloud.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Ollama Cloud API integration.
+    class OllamaCloud < Provider
+      # Ollama Cloud's dialect of the Chat Completions API.
+      class ChatCompletions < Ollama::ChatCompletions
+        include OllamaCloud::Models
+      end
+
+      protocol :chat_completions, ChatCompletions
+
+      def api_base
+        @config.ollama_cloud_api_base || 'https://ollama.com/v1'
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{@config.ollama_cloud_api_key}" }
+      end
+
+      class << self
+        def configuration_options
+          %i[ollama_cloud_api_key ollama_cloud_api_base]
+        end
+
+        def configuration_requirements
+          %i[ollama_cloud_api_key]
+        end
+
+        # Returns +true+: Ollama retires cloud models faster than the
+        # registry tracks them, so model ids are accepted as given. Call
+        # RubyLLM.models.refresh to pull the live catalog.
+        def assume_models_exist?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai/capabilities.rb

@@ -3,270 +3,65 @@
 module RubyLLM
   module Providers
     class OpenAI
-      # Provider-level capability checks and narrow registry fallbacks.
+      # Feature capability gaps not represented in upstream model catalogs.
       module Capabilities
-        module_function
-
-        MODEL_PATTERNS = {
-          gpt_image15: /^gpt-image-1\.5/,
-          gpt_image_mini: /^gpt-image-1-mini/,
-          gpt_image: /^gpt-image-1(?:$|-)/,
-          gpt41: /^gpt-4\.1(?!-(?:mini|nano))/,
-          gpt41_mini: /^gpt-4\.1-mini/,
-          gpt41_nano: /^gpt-4\.1-nano/,
-          gpt4: /^gpt-4(?:-\d{6})?$/,
-          gpt4_turbo: /^gpt-4(?:\.5)?-(?:\d{6}-)?(preview|turbo)/,
-          gpt35_turbo: /^gpt-3\.5-turbo/,
-          gpt4o: /^gpt-4o(?!-(?:mini|audio|realtime|transcribe|tts|search))/,
-          gpt4o_audio: /^gpt-4o-(?:audio)/,
-          gpt4o_mini: /^gpt-4o-mini(?!-(?:audio|realtime|transcribe|tts|search))/,
-          gpt4o_mini_audio: /^gpt-4o-mini-audio/,
-          gpt4o_mini_realtime: /^gpt-4o-mini-realtime/,
-          gpt4o_mini_transcribe: /^gpt-4o-mini-transcribe/,
-          gpt4o_mini_tts: /^gpt-4o-mini-tts/,
-          gpt4o_realtime: /^gpt-4o-realtime/,
-          gpt4o_search: /^gpt-4o-search/,
-          gpt4o_transcribe: /^gpt-4o-transcribe/,
-          gpt5: /^gpt-5(?!.*(?:mini|nano))/,
-          gpt5_mini: /^gpt-5.*mini/,
-          gpt5_nano: /^gpt-5.*nano/,
-          o1: /^o1(?!-(?:mini|pro))/,
-          o1_mini: /^o1-mini/,
-          o1_pro: /^o1-pro/,
-          o3_mini: /^o3-mini/,
-          babbage: /^babbage/,
-          davinci: /^davinci/,
-          embedding3_large: /^text-embedding-3-large/,
-          embedding3_small: /^text-embedding-3-small/,
-          embedding_ada: /^text-embedding-ada/,
-          tts1: /^tts-1(?!-hd)/,
-          tts1_hd: /^tts-1-hd/,
-          whisper: /^whisper/,
-          moderation: /^(?:omni|text)-moderation/
-        }.freeze
-
-        PRICES = {
-          gpt_image: {
-            text: { input: 5.0, cached_input: 1.25 },
-            images: { input: 10.0, cached_input: 2.5, output: 40.0 }
-          },
-          gpt_image_mini: {
-            text: { input: 2.0, cached_input: 0.2 },
-            images: { input: 2.5, cached_input: 0.25, output: 8.0 }
-          },
-          gpt_image15: {
-            text: { input: 5.0, cached_input: 1.25, output: 10.0 },
-            images: { input: 8.0, cached_input: 2.0, output: 32.0 }
-          },
-          gpt5: { input: 1.25, output: 10.0, cached_input: 0.125 },
-          gpt5_mini: { input: 0.25, output: 2.0, cached_input: 0.025 },
-          gpt5_nano: { input: 0.05, output: 0.4, cached_input: 0.005 },
-          gpt41: { input: 2.0, output: 8.0, cached_input: 0.5 },
-          gpt41_mini: { input: 0.4, output: 1.6, cached_input: 0.1 },
-          gpt41_nano: { input: 0.1, output: 0.4 },
-          gpt4: { input: 10.0, output: 30.0 },
-          gpt4_turbo: { input: 10.0, output: 30.0 },
-          gpt35_turbo: { input: 0.5, output: 1.5 },
-          gpt4o: { input: 2.5, output: 10.0 },
-          gpt4o_audio: { input: 2.5, output: 10.0 },
-          gpt4o_mini: { input: 0.15, output: 0.6 },
-          gpt4o_mini_audio: { input: 0.15, output: 0.6 },
-          gpt4o_mini_realtime: { input: 0.6, output: 2.4 },
-          gpt4o_mini_transcribe: { input: 1.25, output: 5.0 },
-          gpt4o_mini_tts: { input: 0.6, output: 12.0 },
-          gpt4o_realtime: { input: 5.0, output: 20.0 },
-          gpt4o_search: { input: 2.5, output: 10.0 },
-          gpt4o_transcribe: { input: 2.5, output: 10.0 },
-          o1: { input: 15.0, output: 60.0 },
-          o1_mini: { input: 1.1, output: 4.4 },
-          o1_pro: { input: 150.0, output: 600.0 },
-          o3_mini: { input: 1.1, output: 4.4 },
-          babbage: { input: 0.4, output: 0.4 },
-          davinci: { input: 2.0, output: 2.0 },
-          embedding3_large: { price: 0.13 },
-          embedding3_small: { price: 0.02 },
-          embedding_ada: { price: 0.10 },
-          tts1: { price: 15.0 },
-          tts1_hd: { price: 30.0 },
-          whisper: { price: 0.006 },
-          moderation: { price: 0.0 }
-        }.freeze
-
-        NIL_LIMIT_FAMILIES = %w[
-          gpt_image
-          gpt_image_mini
-          gpt_image15
-          gpt4o_mini_tts
-          tts1
-          tts1_hd
-          whisper
-          moderation
-          embedding3_large
-          embedding3_small
-          embedding_ada
+        TOOL_CAPABILITIES = %w[tool_choice parallel_tool_calls].freeze
+        CHAT_MODELS = %w[
+          gpt-5-chat-latest
+          gpt-5.1-chat-latest
         ].freeze
+        CODEX_MODELS = %w[
+          gpt-5-codex
+          gpt-5.1-codex
+          gpt-5.1-codex-max
+          gpt-5.1-codex-mini
+          gpt-5.2-codex
+        ].freeze
+        SEARCH_MODELS = %w[
+          gpt-4o-mini-search-preview
+          gpt-4o-mini-search-preview-2025-03-11
+          gpt-4o-search-preview
+          gpt-4o-search-preview-2025-03-11
+          gpt-5-search-api
+          gpt-5-search-api-2025-10-14
+        ].freeze
+        DEEP_RESEARCH_MODELS = %w[
+          o3-deep-research
+          o3-deep-research-2025-06-26
+          o4-mini-deep-research
+          o4-mini-deep-research-2025-06-26
+        ].freeze
+        MODERATION_MODELS = %w[
+          omni-moderation-2024-09-26
+          omni-moderation-latest
+        ].freeze
+        TRANSCRIPTION_MODELS = %w[
+          gpt-live-transcribe
+          gpt-realtime-whisper
+          gpt-transcribe
+          gpt-4o-mini-transcribe
+          gpt-4o-mini-transcribe-2025-03-20
+          gpt-4o-mini-transcribe-2025-12-15
+          gpt-4o-transcribe
+          gpt-4o-transcribe-diarize
+          whisper-1
+        ].freeze
+        EXPLICIT_CAPABILITIES = {
+          'function_calling' => (CHAT_MODELS + CODEX_MODELS).freeze,
+          'structured_output' => (CHAT_MODELS + CODEX_MODELS + SEARCH_MODELS).freeze,
+          'vision' => (CHAT_MODELS + CODEX_MODELS + DEEP_RESEARCH_MODELS + MODERATION_MODELS).freeze,
+          'reasoning' => (CODEX_MODELS + DEEP_RESEARCH_MODELS).freeze,
+          'transcription' => TRANSCRIPTION_MODELS,
+          'citations' => SEARCH_MODELS
+        }.freeze
 
-        def supports_tool_choice?(_model_id)
-          true
-        end
-
-        def supports_tool_parallel_control?(_model_id)
-          true
-        end
-
-        def context_window_for(model_id)
-          family = model_family(model_id)
-          return nil if NIL_LIMIT_FAMILIES.include?(family)
-
-          case family
-          when 'gpt41', 'gpt41_mini', 'gpt41_nano' then 1_047_576
-          when 'gpt5', 'gpt5_mini', 'gpt5_nano', 'gpt4_turbo', 'gpt4o', 'gpt4o_audio', 'gpt4o_mini',
-               'gpt4o_mini_audio', 'gpt4o_mini_realtime', 'gpt4o_realtime', 'gpt4o_search',
-               'gpt4o_transcribe', 'o1_mini' then 128_000
-          when 'gpt4' then 8_192
-          when 'gpt4o_mini_transcribe' then 16_000
-          when 'o1', 'o1_pro', 'o3_mini' then 200_000
-          when 'gpt35_turbo' then 16_385
-          else 4_096
-          end
-        end
-
-        def max_tokens_for(model_id)
-          family = model_family(model_id)
-          return nil if NIL_LIMIT_FAMILIES.include?(family)
-
-          case family
-          when 'gpt5', 'gpt5_mini', 'gpt5_nano' then 400_000
-          when 'gpt41', 'gpt41_mini', 'gpt41_nano' then 32_768
-          when 'gpt4' then 8_192
-          when 'gpt35_turbo' then 4_096
-          when 'gpt4o_mini_transcribe' then 2_000
-          when 'o1', 'o1_pro', 'o3_mini' then 100_000
-          when 'o1_mini' then 65_536
-          else 16_384
-          end
-        end
-
-        def critical_capabilities_for(model_id)
-          capabilities = []
-          capabilities << 'function_calling' if supports_functions?(model_id)
-          capabilities << 'structured_output' if supports_structured_output?(model_id)
-          capabilities << 'vision' if supports_vision?(model_id)
-          capabilities << 'reasoning' if model_id.match?(/o\d|gpt-5|codex/)
-          capabilities
-        end
-
-        def pricing_for(model_id)
-          return image_pricing_for(model_id) if image_model?(model_id)
-
-          standard_pricing = {
-            input_per_million: input_price_for(model_id),
-            output_per_million: output_price_for(model_id)
-          }
-
-          cached_price = cached_input_price_for(model_id)
-          standard_pricing[:cache_read_input_per_million] = cached_price if cached_price
-
-          { text_tokens: { standard: standard_pricing } }
-        end
-
-        def model_family(model_id)
-          MODEL_PATTERNS.each do |family, pattern|
-            return family.to_s if model_id.match?(pattern)
-          end
-
-          'other'
-        end
-
-        def supports_vision?(model_id)
-          case model_family(model_id)
-          when 'gpt_image', 'gpt_image_mini', 'gpt_image15', 'gpt5', 'gpt5_mini', 'gpt5_nano', 'gpt41', 'gpt41_mini',
-               'gpt41_nano', 'gpt4', 'gpt4_turbo', 'gpt4o', 'gpt4o_mini', 'o1', 'o1_pro', 'moderation',
-               'gpt4o_search'
-            true
-          else
-            false
-          end
-        end
-
-        def supports_functions?(model_id)
-          case model_family(model_id)
-          when 'gpt5', 'gpt5_mini', 'gpt5_nano', 'gpt41', 'gpt41_mini', 'gpt41_nano', 'gpt4',
-               'gpt4_turbo', 'gpt4o', 'gpt4o_mini', 'o1', 'o1_pro', 'o3_mini'
-            true
-          else
-            false
-          end
-        end
-
-        def supports_structured_output?(model_id)
-          case model_family(model_id)
-          when 'gpt5', 'gpt5_mini', 'gpt5_nano', 'gpt41', 'gpt41_mini', 'gpt41_nano', 'gpt4o',
-               'gpt4o_mini', 'o1', 'o1_pro', 'o3_mini'
-            true
-          else
-            false
+        def self.augment(capabilities, model_id:, **)
+          additions = EXPLICIT_CAPABILITIES.filter_map do |capability, models|
+            capability if models.include?(model_id)
           end
+          supported = capabilities | additions
+          supported | (supported.include?('function_calling') ? TOOL_CAPABILITIES : [])
         end
-
-        def input_price_for(model_id)
-          return family_prices(model_id).dig(:text, :input) if image_model?(model_id)
-
-          price_for(model_id, :input, 0.50)
-        end
-
-        def output_price_for(model_id)
-          return family_prices(model_id).dig(:text, :output) if image_model?(model_id)
-
-          price_for(model_id, :output, 1.50)
-        end
-
-        def cached_input_price_for(model_id)
-          return family_prices(model_id).dig(:text, :cached_input) if image_model?(model_id)
-
-          family = model_family(model_id).to_sym
-          PRICES.fetch(family, {})[:cached_input]
-        end
-
-        def image_model?(model_id)
-          %w[gpt_image gpt_image_mini gpt_image15].include?(model_family(model_id))
-        end
-
-        def image_pricing_for(model_id)
-          text_pricing = {
-            input_per_million: input_price_for(model_id)
-          }
-          cached_text_price = cached_input_price_for(model_id)
-          text_pricing[:cache_read_input_per_million] = cached_text_price if cached_text_price
-
-          image_pricing = {
-            input_per_million: family_prices(model_id).dig(:images, :input),
-            output_per_million: family_prices(model_id).dig(:images, :output)
-          }
-          cached_image_price = family_prices(model_id).dig(:images, :cached_input)
-          image_pricing[:cache_read_input_per_million] = cached_image_price if cached_image_price
-
-          {
-            text_tokens: { standard: text_pricing },
-            images: { standard: image_pricing }
-          }
-        end
-
-        def price_for(model_id, key, fallback)
-          prices = family_prices(model_id)
-          prices = { key => fallback } if prices.empty?
-          prices[key] || prices[:price] || fallback
-        end
-
-        def family_prices(model_id)
-          family = model_family(model_id).to_sym
-          PRICES.fetch(family, {})
-        end
-
-        module_function :context_window_for, :max_tokens_for, :critical_capabilities_for, :pricing_for,
-                        :model_family, :supports_vision?, :supports_functions?, :supports_structured_output?,
-                        :input_price_for, :output_price_for, :cached_input_price_for, :image_model?,
-                        :image_pricing_for, :price_for, :family_prices
       end
     end
   end

data/lib/ruby_llm/providers/openai/models.rb

@@ -3,33 +3,33 @@
 module RubyLLM
   module Providers
     class OpenAI
-      # Models methods of the OpenAI API integration
+      # Provider-owned model catalog reconciliation.
       module Models
-        module_function
+        SNAPSHOT_BASES = {
+          'gpt-3.5-turbo-0125' => 'gpt-3.5-turbo',
+          'gpt-3.5-turbo-1106' => 'gpt-3.5-turbo',
+          'gpt-4-0314' => 'gpt-4',
+          'gpt-4-0613' => 'gpt-4',
+          'gpt-4-turbo-2024-04-09' => 'gpt-4-turbo',
+          'o1-2024-12-17' => 'o1',
+          'o3-mini-2025-01-31' => 'o3-mini'
+        }.freeze
 
-        def models_url
-          'models'
-        end
+        def self.models_dev_alias(model_id, models_dev_by_key, _provider_model = nil)
+          base_id = SNAPSHOT_BASES[model_id]
+          if base_id
+            source = models_dev_by_key["openai:#{base_id}"]
+            return Model.new(source.to_h.merge(id: model_id)) if source
+          end
 
-        def parse_list_models_response(response, slug, capabilities)
-          Array(response.body['data']).map do |model_data|
-            model_id = model_data['id']
+          match = model_id.match(/\A(.+)-(\d{4}-\d{2}-\d{2})\z/)
+          return unless match
 
-            Model::Info.new(
-              id: model_id,
-              name: model_id,
-              provider: slug,
-              created_at: model_data['created'] ? Time.at(model_data['created']) : nil,
-              context_window: capabilities.context_window_for(model_id),
-              max_output_tokens: capabilities.max_tokens_for(model_id),
-              capabilities: capabilities.critical_capabilities_for(model_id),
-              pricing: capabilities.pricing_for(model_id),
-              metadata: {
-                object: model_data['object'],
-                owned_by: model_data['owned_by']
-              }
-            )
-          end
+          source = models_dev_by_key["openai:#{match[1]}"]
+          return unless source&.created_at
+          return unless source.created_at.to_date.to_s == match[2]
+
+          Model.new(source.to_h.merge(id: model_id))
         end
       end
     end

data/lib/ruby_llm/providers/openai/responses.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAI
+      # OpenAI's Responses API, including input-token counting.
+      class Responses < Protocols::Responses
+        include Protocols::Responses::TokenCounting
+        include Protocols::Responses::Compaction
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai.rb

@@ -4,20 +4,26 @@ module RubyLLM
   module Providers
     # OpenAI API integration.
     class OpenAI < Provider
-      include OpenAI::Chat
-      include OpenAI::Embeddings
-      include OpenAI::Models
-      include OpenAI::Moderation
-      include OpenAI::Streaming
-      include OpenAI::Tools
-      include OpenAI::Images
-      include OpenAI::Media
-      include OpenAI::Transcription
+      protocol :responses, OpenAI::Responses, batches: Protocols::Responses::Batches
+      protocol :chat_completions, Protocols::ChatCompletions, batches: Protocols::ChatCompletions::Batches
+      protocol :embeddings, Protocols::ChatCompletions,
+               batches: Protocols::ChatCompletions::EmbeddingBatches
+      protocol :files, Protocols::OpenAI::Files
+
+      RATE_LIMIT_RESET_HEADERS = %w[x-ratelimit-reset-requests x-ratelimit-reset-tokens].freeze
+      RESET_DURATION_UNITS = { 'h' => 3600, 'm' => 60, 's' => 1, 'ms' => 0.001 }.freeze
 
       def api_base
         @config.openai_api_base || 'https://api.openai.com/v1'
       end
 
+      # Audio, realtime, and dedicated search models only exist on Chat Completions.
+      def protocol_for(model, **)
+        return protocols[:chat_completions] if Capabilities::SEARCH_MODELS.include?(model.id)
+
+        model.id.match?(/audio|realtime/) ? protocols[:chat_completions] : super
+      end
+
       def headers
         {
           'Authorization' => "Bearer #{@config.openai_api_key}",
@@ -26,15 +32,37 @@ module RubyLLM
         }.compact
       end
 
-      def maybe_normalize_temperature(temperature, model)
-        OpenAI::Temperature.normalize(temperature, model.id)
+      # OpenAI reports when each rate limit resets in its own headers,
+      # as durations like "6m0s", "7.66s" or "76ms".
+      def retry_delay(response)
+        headers = response.response_headers
+        return unless headers
+
+        RATE_LIMIT_RESET_HEADERS.filter_map { |header| parse_reset_duration(headers[header]) }.max
+      end
+
+      def find_batch(id)
+        batch = super
+        protocol = batch_protocol_for_endpoint(batch[:endpoint])
+
+        protocol ? batch.merge(batch_protocol: protocol) : batch
+      end
+
+      def batch_results(id, batch_protocol: nil)
+        super(id, batch_protocol: resolve_batch_protocol(batch_protocol) || batch_protocol_for_stored_batch(id))
       end
 
+      def batch_cost_multiplier(**) = 0.5
+
       class << self
         def capabilities
           OpenAI::Capabilities
         end
 
+        def models_dev_alias(...)
+          OpenAI::Models.models_dev_alias(...)
+        end
+
         def configuration_options
           %i[
             openai_api_key
@@ -49,6 +77,59 @@ module RubyLLM
           %i[openai_api_key]
         end
       end
+
+      private
+
+      def parse_reset_duration(value)
+        duration = value.to_s
+        parts = duration.scan(/(\d+(?:\.\d+)?)(ms|h|m|s)/)
+        return if parts.empty?
+        return unless parts.map { |amount, unit| "#{amount}#{unit}" }.join == duration
+
+        parts.sum { |amount, unit| amount.to_f * RESET_DURATION_UNITS[unit] }
+      end
+
+      def batch_protocol
+        batch_protocol_for_name(:responses)
+      end
+
+      def batch_protocol_for(requests)
+        names = requests.map { |request| batch_protocol_name_for(request.fetch(:payload)) }.uniq
+        return batch_protocol_for_name(names.first) if names.one?
+
+        raise Error, 'openai batch requests must target one endpoint per submission'
+      end
+
+      def batch_protocol_name_for(payload)
+        input = payload[:input] || payload['input']
+        return :embeddings if embeddings_input?(input)
+        return :responses if input
+        return :chat_completions if payload.key?(:messages) || payload.key?('messages')
+
+        raise Error, 'openai batch requests only support chat, responses, or embedding payloads'
+      end
+
+      # Responses payloads carry the conversation as an array of message hashes
+      # under :input; embedding payloads put the text itself there.
+      def embeddings_input?(input)
+        input.is_a?(String) || (input.is_a?(Array) && !input.empty? && input.all?(String))
+      end
+
+      def batch_protocol_for_stored_batch(id)
+        data = @connection.get("batches/#{id}").body
+        batch_protocol_for_endpoint(data['endpoint']) || batch_protocol
+      end
+
+      def batch_protocol_for_endpoint(endpoint)
+        case endpoint.to_s.delete_prefix('/')
+        when 'v1/responses', 'responses'
+          batch_protocol_for_name(:responses)
+        when 'v1/chat/completions', 'chat/completions'
+          batch_protocol_for_name(:chat_completions)
+        when 'v1/embeddings', 'embeddings'
+          batch_protocol_for_name(:embeddings)
+        end
+      end
     end
   end
 end