ruby_llm 1.16.0 → 2.0.0.rc2

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

@@ -3,16 +3,14 @@
 module RubyLLM
   module Providers
     class Anthropic
-      # Provider-level capability checks used outside the model registry.
+      # Feature capability gaps not represented in upstream model catalogs.
       module Capabilities
-        module_function
+        TOOL_CAPABILITIES = %w[tool_choice parallel_tool_calls].freeze
 
-        def supports_tool_choice?(_model_id)
-          true
-        end
+        def self.augment(capabilities, **)
+          return capabilities unless capabilities.include?('function_calling')
 
-        def supports_tool_parallel_control?(_model_id)
-          true
+          capabilities | TOOL_CAPABILITIES
         end
       end
     end

data/lib/ruby_llm/providers/anthropic.rb

@@ -4,12 +4,8 @@ module RubyLLM
   module Providers
     # Anthropic Claude API integration.
     class Anthropic < Provider
-      include Anthropic::Chat
-      include Anthropic::Embeddings
-      include Anthropic::Media
-      include Anthropic::Models
-      include Anthropic::Streaming
-      include Anthropic::Tools
+      protocol :anthropic, Protocols::Anthropic, batches: Protocols::Anthropic::Batches
+      protocol :files, Protocols::Anthropic::Files
 
       def api_base
         @config.anthropic_api_base || 'https://api.anthropic.com'
@@ -22,6 +18,8 @@ module RubyLLM
         }
       end
 
+      def batch_cost_multiplier(**) = 0.5
+
       class << self
         def capabilities
           Anthropic::Capabilities

data/lib/ruby_llm/providers/azure/audio.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Azure
+      # Audio endpoints for Azure OpenAI deployments and the v1 API.
+      module Audio
+        def speech_url(model:)
+          @provider.azure_media_url(super)
+        end
+
+        def transcription_url
+          @provider.azure_media_url(super)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Azure
+      # Feature capability gaps not represented in upstream model catalogs.
+      module Capabilities
+        def self.augment(capabilities, model_id:, **)
+          return capabilities unless model_id == 'grok-4-1-fast-non-reasoning'
+
+          capabilities | %w[tool_choice parallel_tool_calls]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/azure/chat.rb

@@ -9,15 +9,8 @@ module RubyLLM
           azure_endpoint(:chat)
         end
 
-        def format_messages(messages)
-          messages.map do |msg|
-            {
-              role: format_role(msg.role),
-              content: Media.format_content(msg.content),
-              tool_calls: format_tool_calls(msg.tool_calls),
-              tool_call_id: msg.tool_call_id
-            }.compact.merge(format_thinking(msg))
-          end
+        def format_content(content, attachments = [])
+          Media.format_content(content, attachments)
         end
 
         def format_role(role)

data/lib/ruby_llm/providers/azure/chat_completions/batches.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Azure
+      class ChatCompletions
+        # Azure OpenAI exposes the OpenAI file-backed Batch API under /openai/v1,
+        # but batch endpoint names omit the /v1 prefix inside the create body.
+        module Batches
+          include Protocols::ChatCompletions::Batches
+
+          private
+
+          def batch_endpoint
+            super.delete_prefix('/v1')
+          end
+
+          def batch_create_url
+            "#{@provider.azure_openai_v1_base}/batches"
+          end
+
+          def batch_url(id)
+            "#{@provider.azure_openai_v1_base}/batches/#{id}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/azure/chat_completions.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Azure < Provider
+      # Azure's dialect of the Chat Completions API. Endpoints depend on how
+      # the configured api_base is shaped (deployment, resource, or openai/v1).
+      class ChatCompletions < Protocols::ChatCompletions
+        include Azure::Chat
+        include Azure::Embeddings
+        include Azure::Media
+        include Azure::Models
+        include Azure::Videos
+        include Azure::Images
+        include Azure::Audio
+
+        def azure_endpoint(kind)
+          parts = azure_base_parts
+
+          case kind
+          when :chat
+            chat_endpoint(parts)
+          when :embeddings
+            embeddings_endpoint(parts)
+          when :models
+            models_endpoint(parts)
+          else
+            raise ArgumentError, "Unknown Azure endpoint kind: #{kind.inspect}"
+          end
+        end
+
+        private
+
+        def azure_base_parts
+          @provider.azure_base_parts
+        end
+
+        def chat_endpoint(parts)
+          case parts[:mode]
+          when :chat_endpoint
+            ''
+          when :deployment_base
+            with_api_version('chat/completions', parts[:version] || Azure::DEFAULT_CHAT_API_VERSION)
+          when :openai_v1_base
+            with_api_version('chat/completions', parts[:version])
+          else
+            with_api_version('models/chat/completions', parts[:version] || Azure::DEFAULT_CHAT_API_VERSION)
+          end
+        end
+
+        def embeddings_endpoint(parts)
+          case parts[:mode]
+          when :deployment_base
+            with_api_version('embeddings', parts[:version] || Azure::DEFAULT_EMBEDDINGS_API_VERSION)
+          when :openai_v1_base
+            with_api_version('embeddings', parts[:version])
+          else
+            "#{parts[:root]}/openai/v1/embeddings"
+          end
+        end
+
+        def models_endpoint(parts)
+          case parts[:mode]
+          when :openai_v1_base
+            with_api_version('models', parts[:version] || Azure::DEFAULT_MODELS_API_VERSION)
+          else
+            "#{parts[:root]}/openai/v1/models?api-version=#{parts[:version] || Azure::DEFAULT_MODELS_API_VERSION}"
+          end
+        end
+
+        def with_api_version(path, version)
+          return path unless version
+
+          separator = path.include?('?') ? '&' : '?'
+          "#{path}#{separator}api-version=#{version}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/azure/cohere.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Azure
+      # Azure endpoints and deployment names for the native Cohere APIs.
+      class Cohere < Protocols::Cohere
+        abstract :render_payload, :completion_url, :models_url, :ocr_url, :transcription_url, :tokenization_url
+        undef_method :create_batch, :find_batch, :cancel_batch, :batch_results
+
+        EMBEDDING_MODEL_ALIASES = {
+          'Cohere-embed-v3-english' => 'embed-english-v3.0',
+          'Cohere-embed-v3-multilingual' => 'embed-multilingual-v3.0'
+        }.freeze
+        private_constant :EMBEDDING_MODEL_ALIASES
+
+        def embedding_url(...)
+          @provider.azure_cohere_url('embed')
+        end
+
+        def rerank_url
+          @provider.azure_cohere_url('rerank')
+        end
+
+        private
+
+        def separate_image_embeddings?(model)
+          super(EMBEDDING_MODEL_ALIASES.fetch(model, model))
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/azure/embeddings.rb

@@ -11,12 +11,13 @@ module RubyLLM
           azure_endpoint(:embeddings)
         end
 
-        def render_embedding_payload(text, model:, dimensions:)
+        # rubocop:disable-next Lint/UnusedMethodArgument
+        def render_embedding_payload(text, model:, dimensions:, task_type: nil, title: nil, provider_options: {})
           {
             model: model,
             input: [text].flatten,
             dimensions: dimensions
-          }.compact
+          }.compact.merge(provider_options)
         end
       end
     end

data/lib/ruby_llm/providers/azure/images.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Azure
+      # Azure image endpoints use multipart uploads for edits.
+      module Images
+        def images_url(with: nil, mask: nil)
+          @provider.azure_media_url(super)
+        end
+
+        def render_edit_payload(prompt, size:, provider_options:, **options)
+          super(prompt, size:, provider_options: { size: size }.compact.merge(provider_options), **options)
+        end
+
+        def json_image_references?(_model)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/azure/media.rb

@@ -7,28 +7,19 @@ module RubyLLM
       module Media
         module_function
 
-        def format_content(content) # rubocop:disable Metrics/PerceivedComplexity
-          return content.value if content.is_a?(RubyLLM::Content::Raw)
-          return content.to_json if content.is_a?(Hash) || content.is_a?(Array)
-          return content unless content.is_a?(Content)
-
-          parts = []
-          parts << OpenAI::Media.format_text(content.text) if content.text
-
-          content.attachments.each do |attachment|
+        def format_content(content, attachments = [])
+          Protocols::ChatCompletions::Media.format_parts(content, attachments) do |attachment|
             case attachment.type
             when :image
-              parts << format_image(attachment)
+              format_image(attachment)
             when :audio
-              parts << OpenAI::Media.format_audio(attachment)
+              Protocols::ChatCompletions::Media.format_audio(attachment)
             when :text
-              parts << OpenAI::Media.format_text_file(attachment)
+              Protocols::ChatCompletions::Media.format_text_file(attachment)
             else
               raise UnsupportedAttachmentError, attachment.mime_type
             end
           end
-
-          parts
         end
 
         def format_image(image)

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

@@ -8,6 +8,41 @@ module RubyLLM
         def models_url
           azure_endpoint(:models)
         end
+
+        # Azure reports the same id once per region it is offered in, and keeps
+        # returning models whose inference deprecation date has passed.
+        def parse_list_models_response(response, slug)
+          Array(response.body['data'])
+            .uniq { |model_data| model_data['id'] }
+            .reject { |model_data| azure_inference_retired?(model_data) }
+            .map { |model_data| azure_model(model_data, slug) }
+        end
+
+        def azure_inference_retired?(model_data)
+          retires_at = model_data.dig('deprecation', 'inference')
+          retires_at.is_a?(Numeric) && Time.at(retires_at) < Time.now
+        end
+
+        def azure_model(model_data, slug)
+          Model.new(
+            id: model_data['id'],
+            name: model_data['id'],
+            provider: slug,
+            created_at: model_data['created_at'] ? Time.at(model_data['created_at']) : nil,
+            modalities: azure_modalities(model_data['capabilities'] || {}),
+            metadata: {
+              object: model_data['object'],
+              lifecycle_status: model_data['lifecycle_status'],
+              inference_retires_at: model_data.dig('deprecation', 'inference')
+            }.compact
+          )
+        end
+
+        def azure_modalities(capabilities)
+          return { input: ['text'], output: ['embeddings'] } if capabilities['embeddings']
+
+          { input: ['text'], output: ['text'] }
+        end
       end
     end
   end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Azure < Provider
+      # Azure's dialect of the OpenAI Responses API, served from the
+      # implicitly versioned openai/v1 base. The model field carries the
+      # deployment name, as on Chat Completions. Azure rejects the
+      # user_data file upload purpose.
+      class Responses < Protocols::Responses
+        include Azure::Videos
+        include Azure::Images
+        include Azure::Audio
+        include Protocols::Responses::Compaction
+
+        def completion_url
+          "#{@provider.azure_openai_v1_base}/responses"
+        end
+
+        def provider_file_upload_options(_attachment)
+          { purpose: 'assistants' }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/azure/videos.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Azure
+      # Sora video generation jobs on Azure OpenAI. The API lives under
+      # the resource's /openai/v1 base and is versioned 'preview' while
+      # Sora is in preview.
+      module Videos
+        API_VERSION = 'preview'
+
+        def video_url
+          azure_video_url('video/generations/jobs')
+        end
+
+        def render_video_payload(prompt, model:, with: [], provider_options: {}) # rubocop:disable Lint/UnusedMethodArgument
+          { model: model, prompt: prompt }.merge(provider_options)
+        end
+
+        def parse_video_job(response, model:)
+          id = response.body['id']
+          raise Error.new('Azure did not return a video generation job', response:) unless id
+
+          VideoJob.new(id: id, protocol: self, model: model, raw: response.body)
+        end
+
+        def video_job_url(job)
+          azure_video_url("video/generations/jobs/#{job.id}")
+        end
+
+        def parse_video_job_status(response, job:) # rubocop:disable Lint/UnusedMethodArgument
+          body = response.body
+          case body['status']
+          when 'succeeded' then { status: :completed, raw: body }
+          when 'failed', 'cancelled'
+            { status: :failed, raw: body, error: body['failure_reason'] || body['status'] }
+          else { status: :pending, raw: body }
+          end
+        end
+
+        def download_video(job)
+          generation_id = job.raw.dig('generations', 0, 'id')
+          raise Error, 'Azure video job has no generations' unless generation_id
+
+          response = @connection.get azure_video_url("video/generations/#{generation_id}/content/video")
+
+          Video.new(
+            data: response.body,
+            mime_type: response.headers['content-type'] || 'video/mp4',
+            model: job.raw['model'] || job.model,
+            duration: job.raw['n_seconds'],
+            raw: job.raw
+          )
+        end
+
+        private
+
+        def azure_video_url(path)
+          "#{@provider.azure_openai_v1_base}/#{path}?api-version=#{API_VERSION}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/azure.rb

@@ -3,79 +3,80 @@
 module RubyLLM
   module Providers
     # Azure AI Foundry / OpenAI-compatible API integration.
-    class Azure < OpenAI
-      AZURE_DEFAULT_CHAT_API_VERSION = '2024-05-01-preview'
-      AZURE_DEFAULT_MODELS_API_VERSION = 'preview'
+    class Azure < Provider
+      DEFAULT_CHAT_API_VERSION = '2024-05-01-preview'
+      DEFAULT_EMBEDDINGS_API_VERSION = '2024-05-01-preview'
+      DEFAULT_MODELS_API_VERSION = 'preview'
 
-      include Azure::Chat
-      include Azure::Embeddings
-      include Azure::Media
-      include Azure::Models
+      protocol :chat_completions, Azure::ChatCompletions, batches: Azure::ChatCompletions::Batches
+      protocol :responses, Azure::Responses
+      protocol :files, Protocols::Azure::Files
+      protocol :cohere, Azure::Cohere
 
       def api_base
         @config.azure_api_base
       end
 
+      # Deployments named after gpt-5.4+ models need the Responses API for
+      # tool use, so they route there automatically. Deployment names often
+      # differ from model ids, so the routing stays conservative; an explicit
+      # protocol: or the azure_protocol configuration option overrides it.
+      def protocol_for(model, operation: nil, **)
+        return protocols[:cohere] if operation == :rerank
+        if operation == :embed &&
+           %w[Cohere-embed-v3-english Cohere-embed-v3-multilingual embed-v-4-0].include?(model.id)
+          return protocols[:cohere]
+        end
+
+        model.id.match?(/gpt-5\.[4-9]|gpt-5\d/) ? protocols[:responses] : super
+      end
+
       def headers
-        if @config.azure_api_key
+        if @config.azure_api_key && URI.parse(api_base).host&.end_with?('.models.ai.azure.com')
+          { 'Authorization' => "Bearer #{@config.azure_api_key}" }
+        elsif @config.azure_api_key
           { 'api-key' => @config.azure_api_key }
         else
           { 'Authorization' => "Bearer #{@config.azure_ai_auth_token}" }
         end
       end
 
-      def configured?
-        self.class.configured?(@config)
+      def batch_cost_multiplier(**) = 0.5
+
+      def azure_cohere_url(operation) # :nodoc:
+        base = azure_base_parts[:path_base]
+        base = if base.include?('/providers/cohere')
+                 base.sub(%r{/providers/cohere.*\z}, '/providers/cohere')
+               elsif URI.parse(base).host&.end_with?('.models.ai.azure.com')
+                 base.sub(%r{/v2(?:/.*)?\z}, '')
+               else
+                 "#{azure_base_parts[:root]}/providers/cohere"
+               end
+        "#{base}/v2/#{operation}"
       end
 
-      def azure_endpoint(kind)
+      def azure_openai_v1_base
         parts = azure_base_parts
-
-        case kind
-        when :chat
-          chat_endpoint(parts)
-        when :embeddings
-          embeddings_endpoint(parts)
-        when :models
-          models_endpoint(parts)
+        if parts[:mode] == :openai_v1_base
+          parts[:path_base]
         else
-          raise ArgumentError, "Unknown Azure endpoint kind: #{kind.inspect}"
+          "#{parts[:root]}/openai/v1"
         end
       end
 
-      class << self
-        def configuration_options
-          %i[azure_api_base azure_api_key azure_ai_auth_token]
-        end
-
-        def configuration_requirements
-          %i[azure_api_base]
-        end
-
-        def configured?(config)
-          config.azure_api_base && (config.azure_api_key || config.azure_ai_auth_token)
-        end
-
-        # Azure works with deployment names, instead of model names
-        def assume_models_exist?
-          true
-        end
-      end
-
-      def ensure_configured!
-        missing = []
-        missing << :azure_api_base unless @config.azure_api_base
-        if @config.azure_api_key.nil? && @config.azure_ai_auth_token.nil?
-          missing << 'azure_api_key or azure_ai_auth_token'
+      def azure_media_url(path) # :nodoc:
+        parts = azure_base_parts
+        if parts[:path_base].include?('/openai/deployments/')
+          base = parts[:path_base].sub(%r{/chat/completions/?\z}, '')
+          version = parts[:version] || '2025-04-01-preview'
+        else
+          base = azure_openai_v1_base
+          version = (parts[:version] if parts[:mode] == :openai_v1_base) || 'preview'
         end
-        return if missing.empty?
 
-        raise ConfigurationError,
-              "Missing configuration for Azure: #{missing.join(', ')}"
+        "#{base.sub(%r{/+\z}, '')}/#{path}?api-version=#{version}"
       end
 
-      private
-
       def azure_base_parts
         @azure_base_parts ||= begin
           raw_base = api_base.to_s.sub(%r{/+\z}, '')
@@ -93,7 +94,6 @@ module RubyLLM
                  end
 
           {
-            raw_base: raw_base,
             path_base: path_base,
             root: azure_host_root(path_base),
             mode: mode,
@@ -102,44 +102,43 @@ module RubyLLM
         end
       end
 
-      def chat_endpoint(parts)
-        case parts[:mode]
-        when :chat_endpoint
-          ''
-        when :deployment_base
-          with_api_version('chat/completions', parts[:version] || AZURE_DEFAULT_CHAT_API_VERSION)
-        when :openai_v1_base
-          with_api_version('chat/completions', parts[:version])
-        else
-          with_api_version('models/chat/completions', parts[:version] || AZURE_DEFAULT_CHAT_API_VERSION)
+      class << self
+        def capabilities
+          Azure::Capabilities
         end
-      end
 
-      def embeddings_endpoint(parts)
-        case parts[:mode]
-        when :deployment_base, :openai_v1_base
-          with_api_version('embeddings', parts[:version])
-        else
-          "#{parts[:root]}/openai/v1/embeddings"
+        def configuration_options
+          %i[azure_api_base azure_api_key azure_ai_auth_token]
         end
-      end
 
-      def models_endpoint(parts)
-        case parts[:mode]
-        when :openai_v1_base
-          with_api_version('models', parts[:version] || AZURE_DEFAULT_MODELS_API_VERSION)
-        else
-          "#{parts[:root]}/openai/v1/models?api-version=#{parts[:version] || AZURE_DEFAULT_MODELS_API_VERSION}"
+        def configuration_requirements
+          %i[azure_api_base]
+        end
+
+        def configured?(config)
+          config.azure_api_base && (config.azure_api_key || config.azure_ai_auth_token)
+        end
+
+        # Azure works with deployment names, instead of model names
+        def assume_models_exist?
+          true
         end
       end
 
-      def with_api_version(path, version)
-        return path unless version
+      def ensure_configured!
+        missing = []
+        missing << :azure_api_base unless @config.azure_api_base
+        if @config.azure_api_key.nil? && @config.azure_ai_auth_token.nil?
+          missing << 'azure_api_key or azure_ai_auth_token'
+        end
+        return if missing.empty?
 
-        separator = path.include?('?') ? '&' : '?'
-        "#{path}#{separator}api-version=#{version}"
+        raise ConfigurationError,
+              "Missing configuration for Azure: #{missing.join(', ')}"
       end
 
+      private
+
       def azure_host_root(base_without_query)
         base_without_query.sub(%r{/(models|openai)/.*\z}, '').sub(%r{/+\z}, '')
       end