ruby_llm 2.1.0 → 2.2.0

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

@@ -24,10 +24,12 @@ module RubyLLM
 
         def finish_reasons = FINISH_REASONS
 
+        def native_tool_namespace?(namespace) = Tools::CLIENT_TOOLSETS.key?(namespace)
+
         def normalize_finish_reason(reason)
           return nil if reason.nil?
 
-          finish_reasons.fetch(reason.to_s) { reason.to_s.to_sym }
+          finish_reasons.fetch(reason.to_s) { reason.to_s.downcase.to_sym }
         end
 
         def completion_url
@@ -64,7 +66,9 @@ module RubyLLM
             thinking: thinking,
             citations: citations,
             caching: caching
-          ).then { |payload| Tools.apply_tool_search(payload) }.slice(*COUNT_TOKENS_KEYS)
+          ).then { |payload| Tools.apply_tool_search(payload) }.slice(*COUNT_TOKENS_KEYS).tap do |payload|
+            payload[:thinking]&.delete(:block_binding)
+          end
         end
 
         def parse_count_tokens_response(response)
@@ -83,13 +87,11 @@ module RubyLLM
         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
+            blocks = Media.render_content(msg.content, msg.attachments).dup
             cache_boundary?(msg, caching:) ? inject_cache_control(blocks, caching:, ttl: msg.cache_ttl) : blocks
           end
         end
@@ -98,23 +100,41 @@ module RubyLLM
                                max_output_tokens: nil)
           payload = {
             model: model.id,
-            messages: format_messages(chat_messages, thinking:, citations:, caching:),
+            messages: render_messages(chat_messages, thinking:, citations:, caching:),
             stream: stream,
             max_tokens: max_output_tokens || model.max_output_tokens || DEFAULT_MAX_OUTPUT_TOKENS
           }
 
           add_thinking_fields(payload, thinking, model)
+          bind_thinking(payload, model)
 
           payload
         end
 
-        def format_messages(messages, thinking: nil, citations: false, caching: nil)
+        # The binding goes on every request, not only once thinking appears
+        # in the history: a thinking setting that changes mid-conversation
+        # invalidates the prompt cache.
+        def bind_thinking(payload, model)
+          return unless thinking_block_binding? && BlockBinding.binds?(model.id)
+
+          bound = BlockBinding.apply(payload[:thinking])
+          payload[:thinking] = bound if bound
+        end
+
+        # Hosts that don't take the binding's beta override this.
+        def thinking_block_binding?
+          true
+        end
+
+        def render_messages(messages, thinking: nil, citations: false, caching: nil)
           rendered = []
           tool_result_blocks = []
+          calls = {}
 
           messages.each do |msg|
+            calls.merge!(msg.tool_calls.to_h)
             if msg.tool_result?
-              tool_result_blocks << Tools.format_tool_result_block(msg)
+              tool_result_blocks << Tools.render_tool_result_block(msg, citations:, tool_call: calls[msg.tool_call_id])
               inject_cache_control(tool_result_blocks, caching:, ttl: msg.cache_ttl) if cache_boundary?(msg, caching:)
               next
             end
@@ -124,7 +144,7 @@ module RubyLLM
               tool_result_blocks = []
             end
 
-            formatted = format_message(msg, thinking:, citations:, caching:)
+            formatted = render_message(msg, thinking:, citations:, caching:)
             rendered << formatted unless formatted[:content].empty?
           end
 
@@ -134,8 +154,9 @@ module RubyLLM
 
         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) }
+            payload[:tools] = Tools.render_tools(tools)
             unless tool_prefs[:choice].nil? && tool_prefs[:calls].nil?
+              Protocol::ToolNamespaces.validate_tool_choice(tools, tool_prefs[:choice])
               payload[:tool_choice] = Tools.build_tool_choice(tool_prefs)
             end
           end
@@ -165,7 +186,13 @@ module RubyLLM
         end
 
         def apply_compaction_headers(headers, _compaction)
-          headers.merge(BETA_HEADER => join_betas(headers[BETA_HEADER], COMPACTION_BETA))
+          add_beta(headers, COMPACTION_BETA)
+        end
+
+        def apply_binding_beta(headers, payload)
+          return headers unless payload[:thinking]&.key?(:block_binding)
+
+          add_beta(headers, BlockBinding::BETA)
         end
 
         # The Files API is still a beta, so a request that references an
@@ -173,22 +200,56 @@ module RubyLLM
         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))
+          add_beta(headers, Files::BETA_HEADER)
+        end
+
+        def apply_mcp_beta(headers)
+          add_beta(headers, Anthropic::MCP_BETA)
         end
 
         def provider_file_source?(payload)
-          blocks = Array(payload[:messages]).flat_map { |message| Array(message[:content]) }
+          blocks = Array(payload[:messages]).flat_map { |message| Array(block_value(message, :content)) }
           blocks.concat(Array(payload[:system]))
-          blocks.any? { |block| block.is_a?(Hash) && block[:source].is_a?(Hash) && block[:source][:type] == 'file' }
+          file_source?(blocks)
+        end
+
+        def file_source?(blocks)
+          blocks.any? do |block|
+            next false unless block.is_a?(Hash)
+
+            source = block_value(block, :source)
+            (source.is_a?(Hash) && block_value(source, :type) == 'file') ||
+              file_source?(Array(block_value(block, :content)))
+          end
+        end
+
+        # A before_request hook can add blocks parsed from JSON.
+        def block_value(block, key)
+          block.fetch(key) { block[key.to_s] }
         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(',')
+          [existing, beta].flat_map { |betas| betas.to_s.split(',') }.map(&:strip).reject(&:empty?).uniq.join(',')
+        end
+
+        def add_beta(headers, beta)
+          headers = canonical_beta_headers(headers)
+          headers.merge(BETA_HEADER => join_betas(headers[BETA_HEADER], beta))
         end
 
-        def supports_provider_file_references?
+        # HTTP header names ignore case but Hash keys do not, so every
+        # spelling a caller used folds into BETA_HEADER before a beta joins it.
+        def canonical_beta_headers(headers)
+          names = headers.keys.select { |name| name.to_s.casecmp?(BETA_HEADER) }
+          return headers if names.empty?
+
+          betas = headers.values_at(*names).reduce { |joined, beta| join_betas(joined, beta) }
+          headers.except(*names).merge(BETA_HEADER => betas)
+        end
+
+        def provider_file_references?
           true
         end
 
@@ -210,11 +271,11 @@ module RubyLLM
         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)
+          text_content, citations = parse_text_and_citations(content_blocks)
+          thinking_content = parse_thinking_content(content_blocks)
+          thinking_signature = parse_thinking_signature(content_blocks)
           tool_use_blocks = Tools.find_tool_uses(content_blocks)
-          server_tool_calls = extract_server_tool_calls(content_blocks)
+          server_tool_calls = parse_server_tool_calls(content_blocks)
 
           build_message(data, content: text_content, citations:, thinking: thinking_content,
                               thinking_signature:, tool_use_blocks:, server_tool_calls:,
@@ -230,7 +291,7 @@ module RubyLLM
             type.end_with?('_tool_result')
         end
 
-        def extract_server_tool_calls(blocks)
+        def parse_server_tool_calls(blocks)
           blocks.select { |block| server_tool_block?(block) }.map do |block|
             ServerToolCall.new(
               type: block['type'],
@@ -243,7 +304,15 @@ module RubyLLM
           end
         end
 
-        def extract_text_and_citations(blocks)
+        # A failed search holds one error object instead of a list of results.
+        def parse_web_sources(message)
+          blocks = message.server_tool_calls.select { |call| call.type == 'web_search_tool_result' }
+          blocks.flat_map { |call| call.result.is_a?(Array) ? call.result : [] }.filter_map do |result|
+            WebSource.new(url: result['url'], title: result['title']) if result['type'] == 'web_search_result'
+          end
+        end
+
+        def parse_text_and_citations(blocks)
           text = +''
           citations = []
 
@@ -272,6 +341,7 @@ module RubyLLM
             text: text,
             start_index: start_index,
             end_index: end_index,
+            source_id: data['source'],
             source_index: data['document_index'] || data['search_result_index'],
             start_page: data['start_page_number'],
             end_page: end_page && (end_page - 1)
@@ -286,14 +356,14 @@ module RubyLLM
 
         # 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)
+        def parse_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)
+        def parse_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')
@@ -307,10 +377,6 @@ module RubyLLM
         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,
@@ -323,29 +389,33 @@ module RubyLLM
             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),
-            cache_write_tokens_by_ttl: extract_cache_write_by_ttl(data),
-            thinking_tokens: thinking_tokens,
+            cache_read_tokens: parse_cache_read_tokens(data),
+            cache_write_tokens: parse_cache_write_tokens(data),
+            cache_write_tokens_by_ttl: parse_cache_write_by_ttl(data),
+            thinking_tokens: usage_thinking_tokens(usage),
             server_tool_use: usage['server_tool_use'],
             finish_reason: normalize_finish_reason(data['stop_reason']),
-            model: data['model'],
+            model: parse_response_model_id(data),
             raw: raw
           )
         end
 
+        def parse_response_model_id(data)
+          data['model']
+        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
+        def render_message(msg, citations: false, caching: nil, **)
           if msg.role == :assistant && msg.raw_content
-            format_raw_assistant_message(msg, caching:)
+            render_raw_assistant_message(msg, caching:)
           elsif msg.tool_call?
-            format_tool_call_with_thinking(msg, caching:)
+            render_tool_call_with_thinking(msg, caching:)
           elsif msg.tool_result?
-            Tools.format_tool_result(msg)
+            Tools.render_tool_result(msg, citations:)
           else
-            format_basic_message_with_thinking(msg, citations: citations, caching:)
+            render_basic_message_with_thinking(msg, citations: citations, caching:)
           end
         end
 
@@ -360,15 +430,15 @@ module RubyLLM
         # 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
+        def render_raw_assistant_message(msg, caching: nil)
+          blocks = Protocol::ReplayedArguments.blank(msg.raw_content.dup, msg, id: 'id', arguments: 'input', empty: {})
           inject_cache_control(blocks, caching:, ttl: msg.cache_ttl) if cache_boundary?(msg, caching:)
 
           { role: 'assistant', content: blocks }
         end
 
-        def format_basic_message_with_thinking(msg, citations: false, caching: nil)
-          content_blocks = msg.role == :assistant ? format_thinking_blocks(msg) : []
+        def render_basic_message_with_thinking(msg, citations: false, caching: nil)
+          content_blocks = msg.role == :assistant ? render_thinking_blocks(msg) : []
 
           append_formatted_content(content_blocks, msg, citations: citations)
           inject_cache_control(content_blocks, caching:, ttl: msg.cache_ttl) if cache_boundary?(msg, caching:)
@@ -379,17 +449,18 @@ module RubyLLM
           }
         end
 
-        def format_tool_call_with_thinking(msg, caching: nil)
+        def render_tool_call_with_thinking(msg, caching: nil)
           content_blocks = prepend_thinking_blocks([], msg)
           append_formatted_content(content_blocks, msg) unless msg.content.nil? || msg.content.empty?
 
-          msg.tool_calls.each_value do |tool_call|
+          msg.tool_calls.each do |tool_call|
             content_blocks << {
               type: 'tool_use',
-              id: tool_call.id,
+              id: tool_call.provider_call_id,
               name: tool_call.name,
-              input: tool_call.arguments
-            }
+              input: tool_call.arguments,
+              toolset_name: tool_call.namespace
+            }.compact
           end
           inject_cache_control(content_blocks, caching:, ttl: msg.cache_ttl) if cache_boundary?(msg, caching:)
 
@@ -400,12 +471,12 @@ module RubyLLM
         end
 
         def prepend_thinking_blocks(content_blocks, msg)
-          content_blocks.unshift(*format_thinking_blocks(msg))
+          content_blocks.unshift(*render_thinking_blocks(msg))
 
           content_blocks
         end
 
-        def format_thinking_blocks(msg)
+        def render_thinking_blocks(msg)
           blocks = msg.raw_reasoning['anthropic'] if msg.raw_reasoning.is_a?(Hash)
           return Support::Utils.deep_dup(blocks) if blocks
 
@@ -422,7 +493,7 @@ module RubyLLM
         end
 
         def append_formatted_content(content_blocks, msg, citations: false)
-          content_blocks.concat(Media.format_content(msg.content, msg.attachments, citations: citations))
+          content_blocks.concat(Media.render_content(msg.content, msg.attachments, citations: citations))
         end
 
         def cache_boundary?(message, caching: nil)
@@ -430,11 +501,9 @@ module RubyLLM
         end
 
         def inject_cache_control(blocks, caching: nil, ttl: 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)
+          return blocks if last[:cache_control] || last['cache_control']
 
           blocks[-1] = last.merge(cache_control: prompt_cache_control(caching, ttl:))
           blocks
@@ -445,13 +514,11 @@ module RubyLLM
           ttl ||= options[:ttl]
 
           { type: CACHE_CONTROL_TYPE }.tap do |control|
-            control[:ttl] = ttl if ttl
+            control[:ttl] = Protocol::CacheLifetime.render(ttl) if 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?
@@ -460,6 +527,8 @@ module RubyLLM
                 "Anthropic prompt caching accepts :ttl, got #{format_cache_option_keys(unsupported)}"
         end
 
+        def cache_option_names = PROMPT_CACHE_OPTIONS
+
         def format_cache_option_keys(keys)
           keys.map { |key| ":#{key}" }.join(', ')
         end
@@ -499,9 +568,10 @@ module RubyLLM
         # 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.
+        # think adaptively, and so does a bare switch, except on generations
+        # that only take a budget, which get the smallest one.
         def thinking_mode(thinking, model, effort, max_tokens)
-          return { type: 'adaptive' } if thinking.enabled == true
+          return toggle_mode(model) if thinking.enabled == true
 
           budget = thinking.budget || effort_budget(effort, model, max_tokens)
           mode = if budget
@@ -515,6 +585,13 @@ module RubyLLM
 
         EFFORT_BUDGETS = { 'low' => 1024, 'medium' => 40_000, 'high' => 63_999 }.freeze
 
+        def toggle_mode(model)
+          budget = model.reasoning_option(:budget_tokens)
+          return { type: 'adaptive' } unless budget && !model.reasoning_option(:effort)
+
+          { type: 'enabled', budget_tokens: [budget[:min].to_i, EFFORT_BUDGETS['low']].max }
+        end
+
         def adaptive_thinking?(thinking, effort, model)
           return true if thinking.display
           return false unless effort
@@ -527,8 +604,6 @@ module RubyLLM
 
           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
 

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

@@ -7,12 +7,20 @@ module RubyLLM
       class Files < Protocols::Files
         BETA_HEADER = 'files-api-2025-04-14'
 
+        def rejected_options(operation)
+          operation == :upload ? %i[purpose uri] : super
+        end
+
         private
 
         def files_url
           'v1/files'
         end
 
+        def render_upload_fields(_attachment, expires_in: nil, **)
+          { expires_in_seconds: expires_in }
+        end
+
         def upload_headers(request)
           file_headers(request)
         end
@@ -28,6 +36,7 @@ module RubyLLM
             filename: data['filename'],
             byte_size: data['size_bytes'],
             created_at: timestamp(data['created_at']),
+            expires_at: timestamp(data['expires_at']),
             mime_type: data['mime_type'],
             downloadable: data['downloadable']
           )

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

@@ -11,39 +11,39 @@ module RubyLLM
           attachment.provider_file? || %i[image pdf text].include?(attachment.type)
         end
 
-        def format_content(content, attachments = [], citations: false)
+        def render_content(content, attachments = [], citations: false)
           parts = []
-          parts << format_text(content) unless content.nil? || content.empty?
+          parts << render_text(content) unless content.nil? || content.empty?
 
           attachments.each do |attachment|
             raise UnsupportedAttachmentError, attachment.mime_type unless supported_attachment?(attachment)
 
             if attachment.provider_file?
-              parts << format_provider_file(attachment, citations: citations)
+              parts << render_provider_file(attachment, citations: citations)
               next
             end
 
             case attachment.type
             when :image
-              parts << format_image(attachment)
+              parts << render_image(attachment)
             when :pdf
-              parts << format_pdf(attachment, citations: citations)
+              parts << render_pdf(attachment, citations: citations)
             when :text
-              parts << (citations ? format_text_document(attachment) : format_text_file(attachment))
+              parts << (citations ? render_text_document(attachment) : render_text_file(attachment))
             end
           end
 
           parts
         end
 
-        def format_text(text)
+        def render_text(text)
           {
             type: 'text',
             text: text
           }
         end
 
-        def format_image(image)
+        def render_image(image)
           if image.url?
             {
               type: 'image',
@@ -64,8 +64,8 @@ module RubyLLM
           end
         end
 
-        def format_provider_file(file, citations: false)
-          return format_provider_image(file) if file.image?
+        def render_provider_file(file, citations: false)
+          return render_provider_image(file) if file.image?
 
           document = {
             type: 'document',
@@ -78,7 +78,7 @@ module RubyLLM
           document
         end
 
-        def format_provider_image(image)
+        def render_provider_image(image)
           {
             type: 'image',
             source: {
@@ -88,7 +88,7 @@ module RubyLLM
           }
         end
 
-        def format_pdf(pdf, citations: false)
+        def render_pdf(pdf, citations: false)
           document = {
             type: 'document',
             source: pdf_source(pdf)
@@ -113,7 +113,7 @@ module RubyLLM
           end
         end
 
-        def format_text_file(text_file)
+        def render_text_file(text_file)
           {
             type: 'text',
             text: text_file.for_llm
@@ -121,7 +121,7 @@ module RubyLLM
         end
 
         # Text attachments become citable documents when citations are enabled.
-        def format_text_document(text_file)
+        def render_text_document(text_file)
           document = {
             type: 'document',
             source: {

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

@@ -70,28 +70,34 @@ module RubyLLM
           end
         end
 
-        def extract_model_id(data)
+        def parse_model_id(data)
           data.dig('message', 'model')
         end
 
-        def extract_input_tokens(data)
-          message_usage(data)['input_tokens']
+        def parse_input_tokens(data)
+          message_usage(data)['input_tokens'] || delta_usage(data)['input_tokens']
         end
 
-        def extract_output_tokens(data)
+        def parse_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')
+        def parse_thinking_tokens(data)
+          usage_thinking_tokens(message_usage(data)) || usage_thinking_tokens(delta_usage(data))
         end
 
-        def extract_cache_read_tokens(data)
+        def usage_thinking_tokens(usage)
+          usage.dig('output_tokens_details', 'thinking_tokens') ||
+            usage.dig('output_tokens_details', 'reasoning_tokens') ||
+            usage['thinking_tokens'] ||
+            usage['reasoning_tokens']
+        end
+
+        def parse_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)
+        def parse_cache_write_tokens(data)
           direct = message_usage(data)['cache_creation_input_tokens'] ||
                    delta_usage(data)['cache_creation_input_tokens']
           return direct if direct
@@ -102,7 +108,7 @@ module RubyLLM
           breakdown.values.compact.sum
         end
 
-        def extract_cache_write_by_ttl(data)
+        def parse_cache_write_by_ttl(data)
           breakdown = message_usage(data)['cache_creation'] || delta_usage(data)['cache_creation']
           return unless breakdown.is_a?(Hash)