ruby_llm 1.15.0 → 2.0.0.rc1

data/lib/ruby_llm/protocols/anthropic/media.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # Handles formatting of media content (images, PDFs, audio) for Anthropic
+      module Media
+        module_function
+
+        def format_content(content, attachments = [], citations: false)
+          parts = []
+          parts << format_text(content) unless content.nil? || content.empty?
+
+          attachments.each do |attachment|
+            if attachment.provider_file?
+              parts << format_provider_file(attachment, citations: citations)
+              next
+            end
+
+            case attachment.type
+            when :image
+              parts << format_image(attachment)
+            when :pdf
+              parts << format_pdf(attachment, citations: citations)
+            when :text
+              parts << (citations ? format_text_document(attachment) : format_text_file(attachment))
+            else
+              raise UnsupportedAttachmentError, attachment.mime_type
+            end
+          end
+
+          parts
+        end
+
+        def format_text(text)
+          {
+            type: 'text',
+            text: text
+          }
+        end
+
+        def format_image(image)
+          if image.url?
+            {
+              type: 'image',
+              source: {
+                type: 'url',
+                url: image.source.to_s
+              }
+            }
+          else
+            {
+              type: 'image',
+              source: {
+                type: 'base64',
+                media_type: image.mime_type,
+                data: image.encoded
+              }
+            }
+          end
+        end
+
+        def format_provider_file(file, citations: false)
+          return format_provider_image(file) if file.image?
+
+          document = {
+            type: 'document',
+            source: {
+              type: 'file',
+              file_id: file.provider_file_id
+            }
+          }
+          enable_citations(document, file) if citations
+          document
+        end
+
+        def format_provider_image(image)
+          {
+            type: 'image',
+            source: {
+              type: 'file',
+              file_id: image.provider_file_id
+            }
+          }
+        end
+
+        def format_pdf(pdf, citations: false)
+          document = {
+            type: 'document',
+            source: pdf_source(pdf)
+          }
+
+          enable_citations(document, pdf) if citations
+          document
+        end
+
+        def pdf_source(pdf)
+          if pdf.url?
+            {
+              type: 'url',
+              url: pdf.source.to_s
+            }
+          else
+            {
+              type: 'base64',
+              media_type: pdf.mime_type,
+              data: pdf.encoded
+            }
+          end
+        end
+
+        def format_text_file(text_file)
+          {
+            type: 'text',
+            text: text_file.for_llm
+          }
+        end
+
+        # Text attachments become citable documents when citations are enabled.
+        def format_text_document(text_file)
+          document = {
+            type: 'document',
+            source: {
+              type: 'text',
+              media_type: 'text/plain',
+              data: text_file.content
+            }
+          }
+
+          enable_citations(document, text_file)
+          document
+        end
+
+        def enable_citations(document, attachment)
+          document[:title] = attachment.filename if attachment.filename
+          document[:citations] = { enabled: true }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/anthropic/models.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # Models methods of the Anthropic API integration
+      module Models
+        ITERATION_TOKEN_KEYS = %w[
+          input_tokens output_tokens cache_read_input_tokens cache_creation_input_tokens
+        ].freeze
+
+        REPORTED_CAPABILITIES = {
+          'batch' => 'batch',
+          'citations' => 'citations',
+          'image_input' => 'vision',
+          'structured_outputs' => 'structured_output',
+          'thinking' => 'reasoning'
+        }.freeze
+
+        def list_models
+          models = []
+          after_id = nil
+
+          loop do
+            response = @connection.get(models_url) do |req|
+              req.params = { limit: 1000 }
+              req.params[:after_id] = after_id if after_id
+            end
+
+            models.concat(parse_list_models_response(response, @provider.slug))
+            break unless response.body['has_more']
+
+            after_id = response.body['last_id']
+          end
+
+          models
+        end
+
+        private
+
+        def models_url
+          'v1/models'
+        end
+
+        def parse_list_models_response(response, slug)
+          Array(response.body['data']).map do |model_data|
+            model_id = model_data['id']
+
+            Model.new(
+              id: model_id,
+              name: model_data['display_name'] || model_id,
+              provider: slug,
+              created_at: Time.parse(model_data['created_at']),
+              context_window: model_data['max_input_tokens'],
+              max_output_tokens: model_data['max_tokens'],
+              capabilities: model_capabilities(model_data),
+              metadata: {}
+            )
+          end
+        end
+
+        def model_capabilities(model_data)
+          reported = model_data['capabilities']
+          return [] unless reported.is_a?(Hash)
+
+          reported.filter_map do |name, detail|
+            REPORTED_CAPABILITIES[name] if detail.is_a?(Hash) && detail['supported']
+          end
+        end
+
+        def extract_model_id(data)
+          data.dig('message', 'model')
+        end
+
+        def extract_input_tokens(data)
+          message_usage(data)['input_tokens']
+        end
+
+        def extract_output_tokens(data)
+          message_usage(data)['output_tokens'] || delta_usage(data)['output_tokens']
+        end
+
+        def extract_thinking_tokens(data)
+          message_usage(data).dig('output_tokens_details', 'thinking_tokens') ||
+            delta_usage(data).dig('output_tokens_details', 'thinking_tokens')
+        end
+
+        def extract_cache_read_tokens(data)
+          message_usage(data)['cache_read_input_tokens'] || delta_usage(data)['cache_read_input_tokens']
+        end
+
+        def extract_cache_write_tokens(data)
+          direct = message_usage(data)['cache_creation_input_tokens'] ||
+                   delta_usage(data)['cache_creation_input_tokens']
+          return direct if direct
+
+          breakdown = message_usage(data)['cache_creation'] || delta_usage(data)['cache_creation']
+          return unless breakdown.is_a?(Hash)
+
+          breakdown.values.compact.sum
+        end
+
+        def message_usage(data)
+          aggregate_usage(data.dig('message', 'usage'))
+        end
+
+        def delta_usage(data)
+          aggregate_usage(data['usage'])
+        end
+
+        # A compacted turn runs the model more than once, and the top-level
+        # counts cover only the final iteration. Everything billed is in
+        # usage.iterations, so their sum is what the request cost.
+        def aggregate_usage(usage)
+          return {} unless usage.is_a?(Hash)
+
+          iterations = usage['iterations']
+          return usage unless iterations.is_a?(Array) && !iterations.empty?
+
+          usage.merge(ITERATION_TOKEN_KEYS.to_h do |key|
+            [key, iterations.sum { |iteration| iteration[key].to_i }]
+          end)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/anthropic/streaming.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # Streaming methods of the Anthropic API integration
+      module Streaming
+        private
+
+        def stream_response(payload, additional_headers = {}, &)
+          # Avoid Net::HTTP's auto-inflate: Cloudflare's gzip flushes
+          # infrequently for SSE, batching chunks until each flush.
+          super(payload, additional_headers.merge('Accept-Encoding' => 'identity'), &)
+        end
+
+        def stream_url
+          completion_url
+        end
+
+        def build_chunk(data)
+          delta_type = data.dig('delta', 'type')
+          track_stream_blocks(data, delta_type)
+
+          Chunk.new(
+            role: :assistant,
+            model: extract_model_id(data),
+            content: extract_content_delta(data, delta_type),
+            citations: extract_citations_delta(data, delta_type),
+            thinking: Thinking.build(
+              text: extract_thinking_delta(data, delta_type),
+              signature: extract_signature_delta(data, delta_type)
+            ),
+            input_tokens: extract_input_tokens(data),
+            output_tokens: extract_output_tokens(data),
+            thinking_tokens: extract_thinking_tokens(data),
+            cache_read_tokens: extract_cache_read_tokens(data),
+            cache_write_tokens: extract_cache_write_tokens(data),
+            server_tool_use: extract_server_tool_use(data),
+            tool_calls: extract_tool_calls(data),
+            finish_reason: normalize_finish_reason(data.dig('delta', 'stop_reason')),
+            **stream_end_fields(data)
+          )
+        end
+
+        def extract_server_tool_use(data)
+          data.dig('message', 'usage', 'server_tool_use') || data.dig('usage', 'server_tool_use')
+        end
+
+        # Reconstructs the response's content blocks from stream events so
+        # turns that used server tools can be replayed verbatim, exactly as
+        # the non-streaming path does with the response body.
+        # Resetting on message_start matters for pause_turn continuations,
+        # which stream several messages through one protocol instance.
+        def track_stream_blocks(data, delta_type)
+          case data['type']
+          when 'message_start' then reset_stream_blocks
+          when 'content_block_start' then track_stream_block_start(data)
+          when 'content_block_delta' then track_stream_block_delta(data, delta_type)
+          when 'content_block_stop' then finalize_stream_block(data['index'])
+          end
+        end
+
+        def reset_stream_blocks
+          @stream_blocks = {}
+          @stream_block_json = {}
+          @saw_server_block = false
+        end
+
+        def track_stream_block_start(data)
+          block = Support::Utils.deep_dup(data['content_block'] || {})
+          @stream_blocks ||= {}
+          @stream_blocks[data['index']] = block
+          @saw_server_block = true if server_tool_block?(block)
+          return unless block['type'].to_s.end_with?('tool_use')
+
+          @stream_block_json ||= {}
+          @stream_block_json[data['index']] = +''
+        end
+
+        def track_stream_block_delta(data, delta_type)
+          block = @stream_blocks&.dig(data['index'])
+          return unless block
+
+          case delta_type
+          when 'text_delta' then block['text'] = block['text'].to_s + data.dig('delta', 'text').to_s
+          when 'thinking_delta' then block['thinking'] = block['thinking'].to_s + data.dig('delta', 'thinking').to_s
+          when 'signature_delta' then block['signature'] = data.dig('delta', 'signature')
+          when 'input_json_delta' then @stream_block_json&.dig(data['index'])&.<< data.dig('delta', 'partial_json').to_s
+          when 'citations_delta' then (block['citations'] ||= []) << data.dig('delta', 'citation')
+          when 'compaction_delta' then block['content'] = block['content'].to_s + data.dig('delta', 'content').to_s
+          end
+        end
+
+        def finalize_stream_block(index)
+          json = @stream_block_json&.dig(index)
+          block = @stream_blocks&.dig(index)
+          return unless json && block
+
+          block['input'] = json.empty? ? block['input'] || {} : parse_stream_block_input(json, block)
+        end
+
+        def parse_stream_block_input(json, block)
+          JSON.parse(json)
+        rescue JSON::ParserError
+          block['input'] || {}
+        end
+
+        def stream_end_fields(data)
+          return {} unless data['type'] == 'message_stop' && @saw_server_block
+
+          blocks = @stream_blocks.sort.map { |_index, block| block }
+          {
+            server_tool_calls: extract_server_tool_calls(blocks),
+            raw_content: blocks
+          }
+        end
+
+        def extract_content_delta(data, delta_type)
+          return data.dig('delta', 'text') if delta_type == 'text_delta'
+
+          nil
+        end
+
+        def extract_citations_delta(data, delta_type)
+          return nil unless delta_type == 'citations_delta'
+
+          citation = data.dig('delta', 'citation')
+          citation ? [Chat.parse_citation(citation)] : nil
+        end
+
+        def extract_thinking_delta(data, delta_type)
+          return data.dig('delta', 'thinking') if delta_type == 'thinking_delta'
+
+          nil
+        end
+
+        def extract_signature_delta(data, delta_type)
+          return data.dig('delta', 'signature') if delta_type == 'signature_delta'
+
+          nil
+        end
+
+        def json_delta?(data)
+          data['type'] == 'content_block_delta' && data.dig('delta', 'type') == 'input_json_delta'
+        end
+
+        def parse_streaming_error(data)
+          error_data = JSON.parse(data)
+          return unless error_data.is_a?(Hash) && error_data['type'] == 'error'
+
+          error = error_data['error']
+          return [500, error.to_s] unless error.is_a?(Hash)
+
+          case error['type']
+          when 'overloaded_error'
+            [529, error['message']]
+          else
+            [500, error['message']]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/{providers → protocols}/anthropic/tools.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  module Providers
+  module Protocols
     class Anthropic
       # Tools methods of the Anthropic API integration
       module Tools
@@ -11,53 +11,45 @@ module RubyLLM
           blocks.select { |c| c['type'] == 'tool_use' }
         end
 
-        def format_tool_call(msg)
-          return { role: 'assistant', content: msg.content.value } if msg.content.is_a?(RubyLLM::Content::Raw)
-
-          content = []
-
-          content << Media.format_text(msg.content) unless msg.content.nil? || msg.content.empty?
-
-          msg.tool_calls.each_value do |tool_call|
-            content << format_tool_use_block(tool_call)
-          end
-
-          {
-            role: 'assistant',
-            content:
-          }
-        end
-
         def format_tool_result(msg)
           {
             role: 'user',
-            content: msg.content.is_a?(RubyLLM::Content::Raw) ? msg.content.value : [format_tool_result_block(msg)]
+            content: [format_tool_result_block(msg)]
           }
         end
 
-        def format_tool_use_block(tool_call)
+        def format_tool_result_block(msg)
           {
-            type: 'tool_use',
-            id: tool_call.id,
-            name: tool_call.name,
-            input: tool_call.arguments
+            type: 'tool_result',
+            tool_use_id: msg.tool_call_id,
+            content: format_tool_result_content(msg)
           }
         end
 
-        def format_tool_result_block(msg)
+        def format_tool_result_content(msg)
+          search_results = RubyLLM::SearchResults.from_content(msg.content)
+          return search_results.results.map { |result| search_result_block(result) } if search_results
+
           content = msg.content
-          content = '(no output)' if content.nil? || (content.respond_to?(:empty?) && content.empty?)
+          content = nil if content && content.empty?
+          content = '(no output)' if content.nil? && msg.attachments.empty?
+
+          Media.format_content(content, msg.attachments)
+        end
 
+        def search_result_block(result)
           {
-            type: 'tool_result',
-            tool_use_id: msg.tool_call_id,
-            content: Media.format_content(content)
+            type: 'search_result',
+            source: result[:url] || result[:title],
+            title: result[:title],
+            content: [{ type: 'text', text: result[:text] }],
+            citations: { enabled: true }
           }
         end
 
         def function_for(tool)
-          input_schema = tool.params_schema ||
-                         RubyLLM::Tool::SchemaDefinition.from_parameters(tool.parameters)&.json_schema
+          input_schema = tool.parameters_schema ||
+                         RubyLLM::Tool::SchemaDefinition.from_parameters(tool.declared_parameters)&.json_schema
 
           declaration = {
             name: tool.name,
@@ -65,19 +57,36 @@ module RubyLLM
             input_schema: input_schema || default_input_schema
           }
 
-          return declaration if tool.provider_params.empty?
+          return declaration if tool.provider_options.empty?
 
-          RubyLLM::Utils.deep_merge(declaration, tool.provider_params)
+          RubyLLM::Support::Utils.deep_merge(declaration, tool.provider_options)
         end
 
         def extract_tool_calls(data)
           if json_delta?(data)
-            { nil => ToolCall.new(id: nil, name: nil, arguments: data.dig('delta', 'partial_json')) }
+            extract_tool_call_delta(data)
+          elsif content_block_start?(data)
+            extract_tool_call_start(data)
           else
             parse_tool_calls(data['content_block'])
           end
         end
 
+        def extract_tool_call_delta(data)
+          { data['index'] => ToolCall.new(id: nil, name: nil, arguments: data.dig('delta', 'partial_json')) }
+        end
+
+        def extract_tool_call_start(data)
+          tool_calls = parse_tool_calls(data['content_block'])
+          return tool_calls if tool_calls.nil? || data['index'].nil?
+
+          { data['index'] => tool_calls.values.first }
+        end
+
+        def content_block_start?(data)
+          data['type'] == 'content_block_start'
+        end
+
         def parse_tool_calls(content_blocks)
           return nil if content_blocks.nil?
 

data/lib/ruby_llm/protocols/anthropic.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    # The Anthropic Messages API.
+    class Anthropic < Protocol
+      include Anthropic::Chat
+      include Anthropic::Embeddings
+      include Anthropic::Media
+      include Anthropic::Models
+      include Anthropic::Streaming
+      include Anthropic::Tools
+
+      # How many times a turn that stops with pause_turn is automatically
+      # continued before RubyLLM returns what it has.
+      MAX_PAUSE_TURN_CONTINUATIONS = 8
+
+      # web_search/web_fetch pin allowed_callers to direct invocation: their
+      # 2026 tool versions otherwise default to requiring programmatic tool
+      # calling, which not every model supports.
+      SERVER_TOOL_ALIASES = {
+        web_search: { tool: { type: 'web_search_20260318', name: 'web_search', allowed_callers: ['direct'] } },
+        web_fetch: { tool: { type: 'web_fetch_20260318', name: 'web_fetch', allowed_callers: ['direct'] } },
+        url_context: { tool: { type: 'web_fetch_20260318', name: 'web_fetch', allowed_callers: ['direct'] } },
+        code_execution: { tool: { type: 'code_execution_20260521', name: 'code_execution' } },
+        mcp: lambda do |options|
+          options = Support::Utils.deep_symbolize_keys(options)
+          name = options[:name] || 'mcp'
+          server = { type: 'url', name: name }.merge(options.slice(:url, :authorization_token))
+          {
+            tool: { type: 'mcp_toolset', mcp_server_name: name }.merge(options.slice(:default_config, :configs)),
+            payload: { mcp_servers: [server] },
+            headers: { 'anthropic-beta' => 'mcp-client-2025-11-20' }
+          }
+        end
+      }.freeze
+
+      def server_tool_aliases
+        SERVER_TOOL_ALIASES
+      end
+
+      # Server tools can pause a long turn with stop_reason pause_turn; the
+      # API expects the conversation back verbatim to continue it. Segments
+      # are merged into the single Message the caller sees.
+      def complete(messages, ...)
+        segments = []
+        current_messages = messages
+
+        MAX_PAUSE_TURN_CONTINUATIONS.times do
+          message = super(current_messages, ...)
+          segments << message
+          break unless message.finish_reason == :pause_turn
+
+          current_messages = current_messages + [message] # rubocop:disable Style/SelfAssignment
+        end
+
+        merge_turn_segments(segments)
+      end
+
+      private
+
+      def sync_response(payload, additional_headers = {})
+        super(payload, apply_files_beta(additional_headers, payload))
+      end
+
+      def stream_response(payload, additional_headers = {}, &)
+        super(payload, apply_files_beta(additional_headers, payload), &)
+      end
+
+      def merge_turn_segments(segments)
+        return segments.first if segments.one?
+
+        final = segments.last
+        Message.new(
+          role: :assistant,
+          content: segments.filter_map(&:content).join,
+          citations: segments.flat_map(&:citations),
+          server_tool_calls: segments.flat_map(&:server_tool_calls),
+          raw_content: merge_raw_content(segments),
+          thinking: final.thinking,
+          tool_calls: merge_tool_calls(segments),
+          tokens: Tokens.aggregate(segments.map(&:tokens)),
+          finish_reason: final.finish_reason,
+          model: final.model,
+          raw: final.raw
+        )
+      end
+
+      def merge_raw_content(segments)
+        merged = segments.flat_map { |segment| segment.raw_content || [] }
+        merged.empty? ? nil : merged
+      end
+
+      def merge_tool_calls(segments)
+        merged = segments.filter_map(&:tool_calls).reduce({}, :merge)
+        merged.empty? ? nil : merged
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/azure/files.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Azure
+      # Azure OpenAI exposes the OpenAI Files API under /openai/v1.
+      class Files < Protocols::OpenAI::Files
+        private
+
+        def files_url
+          "#{@provider.azure_openai_v1_base}/files"
+        end
+      end
+    end
+  end
+end