ruby_llm 1.16.0 → 2.0.0.rc1

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # The Message Batches API: Messages requests processed together,
+      # asynchronously, at half price.
+      module Batches
+        include RubyLLM::Batch::Helpers
+
+        def create_batch(requests)
+          requests = requests.map { |request| { custom_id: request[:custom_id], params: request[:payload] } }
+          response = @connection.post batches_url, { requests: requests }, idempotent: false
+          parse_batch_response response.body
+        end
+
+        def find_batch(id)
+          parse_batch_response @connection.get(batch_url(id)).body
+        end
+
+        def cancel_batch(id)
+          parse_batch_response @connection.post("#{batch_url(id)}/cancel", {}).body
+        end
+
+        # Results come back as JSONL in no particular order; each line carries
+        # the custom_id (our submission index) to match results to requests.
+        def batch_results(id)
+          response = @connection.get "#{batch_url(id)}/results"
+          response.body.each_line.map { |line| parse_batch_result JSON.parse(line) }
+        end
+
+        private
+
+        def batches_url
+          'v1/messages/batches'
+        end
+
+        def batch_url(id)
+          "v1/messages/batches/#{id}"
+        end
+
+        def parse_batch_response(data)
+          request_counts = data['request_counts']
+
+          {
+            id: data['id'],
+            raw_status: data['processing_status'],
+            completed: data['processing_status'] == 'ended',
+            request_counts:,
+            request_count: request_counts&.values&.sum
+          }
+        end
+
+        def parse_batch_status(raw_status, completed:)
+          completed && raw_status == 'ended' ? :succeeded : :pending
+        end
+
+        def parse_batch_result(line)
+          index = batch_result_index(line['custom_id'])
+          result = line['result']
+
+          if result['type'] == 'succeeded'
+            body = result['message']
+            [index, parse_completion_body(body, raw: body)]
+          else
+            status = batch_failure(line['custom_id'], result.dig('error', 'error', 'message'), status: result['type'])
+            [index, nil, status]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,540 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # Chat methods for the Anthropic API implementation
+      module Chat
+        FINISH_REASONS = {
+          'end_turn' => :stop, 'stop_sequence' => :stop, 'max_tokens' => :max_tokens,
+          'model_context_window_exceeded' => :max_tokens, 'tool_use' => :tool_calls, 'refusal' => :content_filter
+        }.freeze
+
+        ANTHROPIC_INLINE_REQUEST_LIMIT = 24 * 1024 * 1024
+        ANTHROPIC_FILE_UPLOAD_LIMIT = 500 * 1024 * 1024
+        CACHE_CONTROL_TYPE = 'ephemeral'
+        PROMPT_CACHE_OPTIONS = %i[ttl].freeze
+        BETA_HEADER = 'anthropic-beta'
+        COMPACTION_BETA = 'compact-2026-01-12'
+        COMPACTION_EDIT_TYPE = 'compact_20260112'
+        COUNT_TOKENS_KEYS = %i[model messages system tools tool_choice thinking].freeze
+
+        module_function
+
+        def finish_reasons = FINISH_REASONS
+
+        def normalize_finish_reason(reason)
+          return nil if reason.nil?
+
+          finish_reasons.fetch(reason.to_s) { reason.to_s.to_sym }
+        end
+
+        def completion_url
+          'v1/messages'
+        end
+
+        def render_payload(messages, tools:, temperature:, model:, stream: false, max_output_tokens: nil,
+                           schema: nil, thinking: nil, citations: false, caching: nil, tool_prefs: nil)
+          warn_unsupported_citations(model) if citations && !model.supports?(:citations)
+          tool_prefs ||= {}
+          system_messages, chat_messages = separate_messages(messages)
+          explicit_boundaries = cache_boundaries?(messages, caching:)
+          system_content = build_system_content(system_messages, caching:)
+
+          build_base_payload(chat_messages, model, stream, thinking, citations: citations, caching:,
+                                                                     max_output_tokens:).tap do |payload|
+            add_optional_fields(payload, system_content:, tools:, tool_prefs:, temperature:, schema:)
+            payload[:cache_control] = prompt_cache_control(caching) if caching && !explicit_boundaries
+          end
+        end
+
+        def count_tokens_url
+          'v1/messages/count_tokens'
+        end
+
+        def render_count_tokens_payload(messages, tools:, model:, tool_prefs: nil, thinking: nil, schema: nil,
+                                        citations: false, caching: nil)
+          render_payload(
+            messages,
+            tools: tools,
+            tool_prefs: tool_prefs,
+            temperature: nil,
+            model: model,
+            schema: schema,
+            thinking: thinking,
+            citations: citations,
+            caching: caching
+          ).slice(*COUNT_TOKENS_KEYS)
+        end
+
+        def parse_count_tokens_response(response)
+          response.body['input_tokens']
+        end
+
+        def warn_unsupported_citations(model)
+          RubyLLM.logger.warn(
+            "#{model.id} does not support citations according to the model registry. " \
+            'with_citations may have no effect.'
+          )
+        end
+
+        def separate_messages(messages)
+          messages.partition { |msg| msg.role == :system }
+        end
+
+        def build_system_content(system_messages, caching: nil)
+          return [] if system_messages.empty?
+
+          # Anthropic's `system` parameter accepts an array of text content blocks
+          # (each optionally with cache_control); each :system message becomes its
+          # own block in the resulting array.
+          system_messages.flat_map do |msg|
+            blocks = Media.format_content(msg.content, msg.attachments).dup
+            cache_boundary?(msg, caching:) ? inject_cache_control(blocks, caching:) : blocks
+          end
+        end
+
+        def build_base_payload(chat_messages, model, stream, thinking, citations: false, caching: nil,
+                               max_output_tokens: nil)
+          payload = {
+            model: model.id,
+            messages: format_messages(chat_messages, thinking:, citations:, caching:),
+            stream: stream,
+            max_tokens: max_output_tokens || model.max_output_tokens || 4096
+          }
+
+          add_thinking_fields(payload, thinking, model)
+
+          payload
+        end
+
+        def format_messages(messages, thinking: nil, citations: false, caching: nil)
+          rendered = []
+          tool_result_blocks = []
+
+          messages.each do |msg|
+            if msg.tool_result?
+              tool_result_blocks << Tools.format_tool_result_block(msg)
+              inject_cache_control(tool_result_blocks, caching:) if cache_boundary?(msg, caching:)
+              next
+            end
+
+            unless tool_result_blocks.empty?
+              rendered << { role: 'user', content: tool_result_blocks }
+              tool_result_blocks = []
+            end
+
+            formatted = format_message(msg, thinking:, citations:, caching:)
+            rendered << formatted unless formatted[:content].empty?
+          end
+
+          rendered << { role: 'user', content: tool_result_blocks } unless tool_result_blocks.empty?
+          rendered
+        end
+
+        def add_optional_fields(payload, system_content:, tools:, tool_prefs:, temperature:, schema: nil)
+          if tools.any?
+            payload[:tools] = tools.values.map { |t| Tools.function_for(t) }
+            unless tool_prefs[:choice].nil? && tool_prefs[:calls].nil?
+              payload[:tool_choice] = Tools.build_tool_choice(tool_prefs)
+            end
+          end
+          payload[:system] = system_content unless system_content.empty?
+          payload[:temperature] = temperature unless temperature.nil?
+          payload[:output_config] = payload.fetch(:output_config, {}).merge(build_output_config(schema)) if schema
+        end
+
+        def apply_end_user(payload, identifier)
+          Support::Utils.deep_merge(payload, { metadata: { user_id: identifier } })
+        end
+
+        # Anthropic compacts through a context_management edit. Omitting the
+        # trigger leaves the API on its own default threshold; the API
+        # rejects an explicit one below its minimum, so RubyLLM passes the
+        # value through rather than second-guessing it.
+        def apply_compaction(payload, compaction)
+          Support::Utils.deep_merge(payload, { context_management: { edits: [compaction_edit(compaction)] } })
+        end
+
+        def compaction_edit(compaction)
+          edit = { type: COMPACTION_EDIT_TYPE }
+          edit[:trigger] = { type: 'input_tokens', value: compaction[:at] } if compaction[:at]
+          edit[:instructions] = compaction[:instructions] if compaction[:instructions]
+          edit[:pause_after_compaction] = true if compaction[:pause_after]
+          edit
+        end
+
+        def apply_compaction_headers(headers, _compaction)
+          headers.merge(BETA_HEADER => join_betas(headers[BETA_HEADER], COMPACTION_BETA))
+        end
+
+        # The Files API is still a beta, so a request that references an
+        # uploaded file has to carry its beta header too.
+        def apply_files_beta(headers, payload)
+          return headers unless provider_file_source?(payload)
+
+          headers.merge(BETA_HEADER => join_betas(headers[BETA_HEADER], Files::BETA_HEADER))
+        end
+
+        def provider_file_source?(payload)
+          blocks = Array(payload[:messages]).flat_map { |message| Array(message[:content]) }
+          blocks.concat(Array(payload[:system]))
+          blocks.any? { |block| block.is_a?(Hash) && block[:source].is_a?(Hash) && block[:source][:type] == 'file' }
+        end
+
+        # Anthropic takes several betas as one comma-separated header, so an
+        # added beta joins whatever a server tool or with_headers already set.
+        def join_betas(existing, beta)
+          (existing.to_s.split(',').map(&:strip).reject(&:empty?) + [beta]).uniq.join(',')
+        end
+
+        def supports_provider_file_references?
+          true
+        end
+
+        def default_large_file_upload_threshold
+          ANTHROPIC_INLINE_REQUEST_LIMIT
+        end
+
+        def provider_file_upload_limit
+          ANTHROPIC_FILE_UPLOAD_LIMIT
+        end
+
+        def provider_file_attachable?(attachment)
+          attachment.image? || attachment.pdf? || attachment.text?
+        end
+
+        def build_output_config(schema)
+          normalized = RubyLLM::Support::Utils.deep_dup(schema[:schema])
+          normalized.delete(:strict)
+          normalized.delete('strict')
+          { format: { type: 'json_schema', schema: normalized } }
+        end
+
+        def parse_completion_body(data, raw:)
+          content_blocks = data['content'] || []
+
+          text_content, citations = extract_text_and_citations(content_blocks)
+          thinking_content = extract_thinking_content(content_blocks)
+          thinking_signature = extract_thinking_signature(content_blocks)
+          tool_use_blocks = Tools.find_tool_uses(content_blocks)
+          server_tool_calls = extract_server_tool_calls(content_blocks)
+
+          build_message(data, content: text_content, citations:, thinking: thinking_content,
+                              thinking_signature:, tool_use_blocks:, server_tool_calls:,
+                              raw_content: server_tool_calls.any? ? content_blocks : nil, raw:)
+        end
+
+        # Any block that is not text, thinking, or a function tool_use is a
+        # provider-executed tool step. Matching by shape rather than by an
+        # allowlist keeps tools Anthropic ships later flowing through.
+        def server_tool_block?(block)
+          type = block['type'].to_s
+          type == 'server_tool_use' || type == 'mcp_tool_use' || type == 'compaction' ||
+            type.end_with?('_tool_result')
+        end
+
+        def extract_server_tool_calls(blocks)
+          blocks.select { |block| server_tool_block?(block) }.map do |block|
+            ServerToolCall.new(
+              type: block['type'],
+              name: block['name'],
+              id: block['id'] || block['tool_use_id'],
+              input: block['input'],
+              result: block['content'],
+              raw: block
+            )
+          end
+        end
+
+        def extract_text_and_citations(blocks)
+          text = +''
+          citations = []
+
+          blocks.each do |block|
+            next unless block['type'] == 'text'
+
+            block_text = block['text'].to_s
+            Array(block['citations']).each do |citation|
+              citations << parse_citation(citation, text: block_text,
+                                                    start_index: text.length,
+                                                    end_index: text.length + block_text.length)
+            end
+            text << block_text
+          end
+
+          [text, citations]
+        end
+
+        def parse_citation(data, text: nil, start_index: nil, end_index: nil)
+          end_page = data['end_page_number']
+
+          Citation.new(
+            url: citation_url(data),
+            title: data['document_title'] || data['title'],
+            cited_text: data['cited_text'],
+            text: text,
+            start_index: start_index,
+            end_index: end_index,
+            source_index: data['document_index'] || data['search_result_index'],
+            start_page: data['start_page_number'],
+            end_page: end_page && (end_page - 1)
+          )
+        end
+
+        # Search result citations carry the developer-provided source string.
+        def citation_url(data)
+          url = data['url'] || data['source']
+          url if url&.match?(%r{\Ahttps?://}i)
+        end
+
+        # An empty thinking text is a real block whose display was omitted;
+        # collapsing it to nil would replay the signature as redacted data.
+        def extract_thinking_content(blocks)
+          thinking_blocks = blocks.select { |c| c['type'] == 'thinking' }
+          return nil if thinking_blocks.empty?
+
+          thinking_blocks.map { |c| c['thinking'] || c['text'] }.join
+        end
+
+        def extract_thinking_signature(blocks)
+          thinking_block = blocks.find { |c| c['type'] == 'thinking' } ||
+                           blocks.find { |c| c['type'] == 'redacted_thinking' }
+          thinking_block&.dig('signature') || thinking_block&.dig('data')
+        end
+
+        def build_message(data, content:, citations:, thinking:, thinking_signature:, tool_use_blocks:, raw:,
+                          server_tool_calls: [], raw_content: nil)
+          usage = aggregate_usage(data['usage'])
+          thinking_tokens = usage.dig('output_tokens_details', 'thinking_tokens') ||
+                            usage.dig('output_tokens_details', 'reasoning_tokens') ||
+                            usage['thinking_tokens'] ||
+                            usage['reasoning_tokens']
+
+          Message.new(
+            role: :assistant,
+            content: content,
+            citations: citations,
+            thinking: Thinking.build(text: thinking, signature: thinking_signature),
+            tool_calls: Tools.parse_tool_calls(tool_use_blocks),
+            server_tool_calls: server_tool_calls,
+            raw_content: raw_content,
+            input_tokens: usage['input_tokens'],
+            output_tokens: usage['output_tokens'],
+            cache_read_tokens: extract_cache_read_tokens(data),
+            cache_write_tokens: extract_cache_write_tokens(data),
+            thinking_tokens: thinking_tokens,
+            server_tool_use: usage['server_tool_use'],
+            finish_reason: normalize_finish_reason(data['stop_reason']),
+            model: data['model'],
+            raw: raw
+          )
+        end
+
+        # Stored thinking blocks replay whether or not this request asks for
+        # thinking: Claude emits them on its own and requires them back on
+        # tool-use turns.
+        def format_message(msg, thinking: nil, citations: false, caching: nil) # rubocop:disable Lint/UnusedMethodArgument
+          if msg.role == :assistant && msg.raw_content
+            format_raw_assistant_message(msg, caching:)
+          elsif msg.tool_call?
+            format_tool_call_with_thinking(msg, caching:)
+          elsif msg.tool_result?
+            Tools.format_tool_result(msg)
+          else
+            format_basic_message_with_thinking(msg, citations: citations, caching:)
+          end
+        end
+
+        # Turns that used server tools replay their provider-shaped blocks
+        # verbatim: the API requires the tool_use/result blocks and their
+        # citations back exactly as returned.
+        def format_raw_assistant_message(msg, caching: nil)
+          blocks = msg.raw_content.dup
+          inject_cache_control(blocks, caching:) if cache_boundary?(msg, caching:)
+
+          { role: 'assistant', content: blocks }
+        end
+
+        def format_basic_message_with_thinking(msg, citations: false, caching: nil)
+          content_blocks = []
+
+          if msg.role == :assistant
+            thinking_block = build_thinking_block(msg.thinking)
+            content_blocks << thinking_block if thinking_block
+          end
+
+          append_formatted_content(content_blocks, msg, citations: citations)
+          inject_cache_control(content_blocks, caching:) if cache_boundary?(msg, caching:)
+
+          {
+            role: convert_role(msg.role),
+            content: content_blocks
+          }
+        end
+
+        def format_tool_call_with_thinking(msg, caching: nil)
+          content_blocks = prepend_thinking_block([], msg)
+          append_formatted_content(content_blocks, msg) unless msg.content.nil? || msg.content.empty?
+
+          msg.tool_calls.each_value do |tool_call|
+            content_blocks << {
+              type: 'tool_use',
+              id: tool_call.id,
+              name: tool_call.name,
+              input: tool_call.arguments
+            }
+          end
+          inject_cache_control(content_blocks, caching:) if cache_boundary?(msg, caching:)
+
+          {
+            role: 'assistant',
+            content: content_blocks
+          }
+        end
+
+        def prepend_thinking_block(content_blocks, msg)
+          thinking_block = build_thinking_block(msg.thinking)
+          content_blocks.unshift(thinking_block) if thinking_block
+
+          content_blocks
+        end
+
+        def build_thinking_block(thinking)
+          return nil unless thinking
+
+          if thinking.text
+            {
+              type: 'thinking',
+              thinking: thinking.text,
+              signature: thinking.signature
+            }.compact
+          elsif thinking.signature
+            {
+              type: 'redacted_thinking',
+              data: thinking.signature
+            }
+          end
+        end
+
+        def append_formatted_content(content_blocks, msg, citations: false)
+          content_blocks.concat(Media.format_content(msg.content, msg.attachments, citations: citations))
+        end
+
+        def cache_boundaries?(messages, caching: nil)
+          caching != false && messages.any?(&:cache_until_here?)
+        end
+
+        def cache_boundary?(message, caching: nil)
+          caching != false && message.cache_until_here?
+        end
+
+        def inject_cache_control(blocks, caching: nil)
+          return blocks if blocks.empty?
+
+          last = blocks.last
+          return blocks if last.is_a?(Hash) && (last[:cache_control] || last['cache_control'])
+          return blocks unless last.is_a?(Hash)
+
+          blocks[-1] = last.merge(cache_control: prompt_cache_control(caching))
+          blocks
+        end
+
+        def prompt_cache_control(caching = nil)
+          options = prompt_cache_options(caching)
+
+          { type: CACHE_CONTROL_TYPE }.tap do |control|
+            control[:ttl] = options[:ttl] if options[:ttl]
+          end
+        end
+
+        def prompt_cache_options(caching)
+          return {} unless caching
+
+          options = caching.to_h.transform_keys(&:to_sym)
+          unsupported = options.keys - PROMPT_CACHE_OPTIONS
+          return options if unsupported.empty?
+
+          raise ArgumentError,
+                "Anthropic prompt caching accepts :ttl, got #{format_cache_option_keys(unsupported)}"
+        end
+
+        def format_cache_option_keys(keys)
+          keys.map { |key| ":#{key}" }.join(', ')
+        end
+
+        def convert_role(role)
+          case role
+          when :tool, :user then 'user'
+          else 'assistant'
+          end
+        end
+
+        def add_thinking_fields(payload, thinking, model)
+          thinking_payload = build_thinking_payload(thinking, model, payload[:max_tokens])
+          return unless thinking_payload
+
+          payload[:thinking] = thinking_payload[:thinking] if thinking_payload[:thinking]
+          return unless thinking_payload[:output_config]
+
+          payload[:output_config] = payload.fetch(:output_config, {}).merge(thinking_payload[:output_config])
+        end
+
+        def build_thinking_payload(thinking, model, max_tokens)
+          return nil unless thinking&.enabled?
+          return { thinking: { type: 'disabled' } } if thinking.enabled == false
+
+          effort = resolve_effort(thinking)
+          return nil if effort == 'none'
+
+          payload = {}
+          mode = thinking_mode(thinking, model, effort, max_tokens)
+          payload[:thinking] = mode if mode
+          payload[:output_config] = { effort: effort } if effort
+          payload
+        end
+
+        # Effort alone never turns thinking on; Claude needs a thinking block.
+        # Generations that take a budget get one sized from the effort with
+        # the levels Bedrock publishes. Generations without a budget option
+        # think adaptively.
+        def thinking_mode(thinking, model, effort, max_tokens)
+          return { type: 'adaptive' } if thinking.enabled == true
+
+          budget = thinking.budget || effort_budget(effort, model, max_tokens)
+          mode = if budget
+                   { type: 'enabled', budget_tokens: budget }
+                 elsif adaptive_thinking?(thinking, effort, model)
+                   { type: 'adaptive' }
+                 end
+          mode[:display] = thinking.display.to_s if mode && thinking.display
+          mode
+        end
+
+        EFFORT_BUDGETS = { 'low' => 1024, 'medium' => 40_000, 'high' => 63_999 }.freeze
+
+        def adaptive_thinking?(thinking, effort, model)
+          return true if thinking.display
+          return false unless effort
+
+          model.reasoning_option(:effort) && !model.reasoning_option(:budget_tokens)
+        end
+
+        def effort_budget(effort, model, max_tokens)
+          return nil unless effort && model.reasoning_option(:budget_tokens)
+
+          budget = EFFORT_BUDGETS.fetch(effort, EFFORT_BUDGETS['high'])
+          minimum = [model.reasoning_option(:budget_tokens)[:min].to_i, 1].max
+          return [budget, minimum].max unless max_tokens
+
+          budget.clamp(minimum, [max_tokens - 1, minimum].max)
+        end
+
+        def resolve_effort(thinking)
+          effort = thinking.effort.to_s
+          effort.empty? ? nil : effort
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # Embeddings methods of the Anthropic API integration
+      module Embeddings
+        def embed(...)
+          raise Error, "Anthropic doesn't support embeddings"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # Anthropic beta Files API.
+      class Files < Protocols::Files
+        BETA_HEADER = 'files-api-2025-04-14'
+
+        private
+
+        def files_url
+          'v1/files'
+        end
+
+        def upload_headers(request)
+          file_headers(request)
+        end
+
+        def file_headers(request)
+          request.headers['anthropic-beta'] = BETA_HEADER
+        end
+
+        def parse_file_response(data)
+          uploaded_file(
+            data,
+            id: data['id'],
+            filename: data['filename'],
+            byte_size: data['size_bytes'],
+            created_at: timestamp(data['created_at']),
+            mime_type: data['mime_type'],
+            downloadable: data['downloadable']
+          )
+        end
+      end
+    end
+  end
+end