ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/message.rb

@@ -67,6 +67,11 @@ module RubyLLM
     # Chat#with_provider_tools and the model used one.
     attr_reader :server_tool_calls
 
+    # The MCP::Result behind a tool result message, when the MCP tool that
+    # returned it has a UI and did not fail, so your app can render the UI
+    # again with the result. +nil+ otherwise.
+    attr_reader :mcp_result
+
     # The provider-shaped content blocks of this assistant message, kept
     # verbatim when the response used server tools so later requests can
     # replay the turn exactly. +nil+ otherwise.
@@ -95,6 +100,7 @@ module RubyLLM
         output: options[:output_tokens],
         cache_read: options[:cache_read_tokens],
         cache_write: options[:cache_write_tokens],
+        cache_write_by_ttl: options[:cache_write_tokens_by_ttl],
         thinking: options[:thinking_tokens],
         server_tool_use: options[:server_tool_use],
         reported_cost: options[:reported_cost]
@@ -105,9 +111,11 @@ module RubyLLM
       @server_tool_calls = Array(options[:server_tool_calls]).map { |call| coerce_value(call, ServerToolCall) }
       @raw_content = options[:raw_content]
       @raw_reasoning = options[:raw_reasoning]
+      @mcp_result = coerce_mcp_result(options[:mcp_result])
       @finish_reason = options[:finish_reason]&.to_sym
       self.ruby_llm_usage_entries = options[:usage_entries] if options[:usage_entries]
       @cache_until_here = options.fetch(:cache_until_here, false)
+      @cache_ttl = options[:cache_ttl] if @cache_until_here
 
       ensure_valid_role
     end
@@ -129,10 +137,11 @@ module RubyLLM
       dup.tap { |message| message.instance_variable_set(:@attachments, wrapped) }
     end
 
-    def without_thinking # :nodoc:
+    def without_native_content(raw_content: nil) # :nodoc:
       dup.tap do |message|
         message.instance_variable_set(:@thinking, nil)
         message.instance_variable_set(:@raw_reasoning, nil)
+        message.instance_variable_set(:@raw_content, raw_content)
         message.instance_variable_set(:@tool_calls, tool_calls_without_thought_signatures)
       end
     end
@@ -209,15 +218,32 @@ module RubyLLM
 
     # Marks this message as an explicit prompt cache boundary. Providers
     # with boundary controls use the conversation up to and including this
-    # message as the cacheable prefix. Returns +self+.
+    # message as the cacheable prefix. Pass +ttl:+ to give this boundary its
+    # own cache lifetime instead of the +ttl:+ from Chat#with_caching, on
+    # providers that set a lifetime per boundary. Returns +self+.
     #
     #   chat.add_message(role: :user, content: long_context).cache_until_here
+    #   chat.add_message(role: :user, content: handbook).cache_until_here(ttl: "1h")
     #
-    def cache_until_here
+    def cache_until_here(ttl: nil)
       @cache_until_here = true
+      @cache_ttl = ttl
       self
     end
 
+    # Returns the cache lifetime given to this message's boundary, such as
+    # <tt>"1h"</tt>, or +nil+ when the chat's caching policy applies.
+    attr_reader :cache_ttl
+
+    def self.cache_boundary_options(value) # :nodoc:
+      return {} if value == true
+
+      options = value.transform_keys(&:to_sym) if value.is_a?(Hash)
+      return options if options && (options.keys - %i[ttl]).empty?
+
+      raise ArgumentError, "cache_until_here accepts true, false, or ttl:, got #{value.inspect}"
+    end
+
     # Returns +true+ if the message carries an explicit prompt cache
     # boundary, +false+ otherwise.
     def cache_until_here?
@@ -227,7 +253,8 @@ module RubyLLM
     # Returns a Hash of the message's attributes, with token counts merged
     # in as +:input_tokens+, +:output_tokens+, and related keys. Omits
     # +nil+ values and empty attachment and citation lists. Includes +:cost+
-    # only when supplied explicitly, preserving unknown costs on round-trip.
+    # only when supplied explicitly, preserving unknown costs on round-trip,
+    # and +:reported_cost+ when the provider reported its own price.
     def to_h
       {
         role: role,
@@ -235,6 +262,7 @@ module RubyLLM
         attachments: list_to_h(attachments),
         model: model,
         cost: @supplied_cost && cost.to_h,
+        reported_cost: tokens.reported_cost,
         tool_calls: tool_calls&.transform_values(&:to_h),
         tool_call_id: tool_call_id,
         thinking: thinking&.text,
@@ -243,8 +271,10 @@ module RubyLLM
         server_tool_calls: list_to_h(server_tool_calls),
         raw_content: raw_content,
         raw_reasoning: raw_reasoning,
+        mcp_result: mcp_result&.dump,
         finish_reason: finish_reason,
-        cache_until_here: cache_until_here? || nil
+        cache_until_here: cache_until_here? || nil,
+        cache_ttl: cache_ttl
       }.merge(tokens.to_h).compact
     end
 
@@ -292,7 +322,8 @@ module RubyLLM
 
     def coerce_thinking(thinking, signature)
       case thinking
-      when nil, Thinking then thinking
+      when Thinking then thinking
+      when nil then Thinking.build(signature: signature)
       when Hash then Thinking.build(**thinking.transform_keys(&:to_sym).slice(:text, :signature))
       else Thinking.build(text: thinking.to_s, signature: signature)
       end
@@ -302,6 +333,10 @@ module RubyLLM
       value.is_a?(Hash) ? klass.from_h(value) : value
     end
 
+    def coerce_mcp_result(value)
+      value.is_a?(Hash) ? MCP::Result.load(value.transform_keys(&:to_s)) : value
+    end
+
     def normalize_content(content)
       return '' if role == :assistant && content.nil? && tool_calls && !tool_calls.empty?
       return content if content.nil? || content.is_a?(String)

data/lib/ruby_llm/model.rb

@@ -171,7 +171,7 @@ module RubyLLM
 
     # Returns the model's primary function, inferred from its output
     # modalities: +:chat+, +:embedding+, +:moderation+, +:image+, +:audio+,
-    # +:video+, or +:rerank+.
+    # +:video+, +:rerank+, or +:judgment+.
     def type
       output = modalities.output
       return :embedding if output.include?('embeddings')
@@ -180,6 +180,7 @@ module RubyLLM
       return :audio if output.include?('audio')
       return :video if output.include?('video')
       return :rerank if output.include?('rerank')
+      return :judgment if output.include?('judgment')
 
       :chat
     end

data/lib/ruby_llm/models/aliases.rb

@@ -5,6 +5,9 @@ require 'json'
 module RubyLLM
   class Models
     class Aliases # :nodoc:
+      LOAD_LOCK = Mutex.new
+      private_constant :LOAD_LOCK
+
       class << self
         def resolve(model_id, provider = nil)
           return model_id unless aliases[model_id]
@@ -17,7 +20,7 @@ module RubyLLM
         end
 
         def aliases
-          @aliases ||= load_aliases
+          @aliases || LOAD_LOCK.synchronize { @aliases ||= load_aliases }
         end
 
         def aliases_file
@@ -26,7 +29,7 @@ module RubyLLM
 
         def load_aliases
           if File.exist?(aliases_file)
-            JSON.parse(File.read(aliases_file))
+            JSON.parse(File.read(aliases_file, encoding: Encoding::UTF_8))
           else
             {}
           end

data/lib/ruby_llm/models/lookup.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Models
+    # Finds registry entries by model id, resolving aliases, provider
+    # registry ids, and deployments, and preferring first-party providers.
+    module Lookup # :nodoc:
+      private
+
+      def models_by_id
+        models = @models
+        index = @model_index
+        index = @model_index = [models, models.group_by(&:id)] unless index && index.first.equal?(models)
+        index.last
+      end
+
+      def find_with_provider(model_id, provider, config = nil)
+        deployed_id = Provider.resolve(provider)&.deployed_model_id(model_id, config || RubyLLM.config)
+        return find_registered(model_id, provider, config) unless deployed_id
+
+        Model.new(find_deployed_model(model_id, deployed_id, provider, config).to_h.merge(id: model_id))
+      end
+
+      def find_deployed_model(deployment, model_id, provider, config)
+        find_registered(model_id, provider, config)
+      rescue ModelNotFoundError
+        raise ConfigurationError, "Deployment #{deployment.inspect} points to unknown model #{model_id.inspect} " \
+                                  "for provider: #{provider.inspect}. #{refresh_registry_guidance}"
+      end
+
+      def find_registered(model_id, provider, config)
+        resolved_id = Aliases.resolve(model_id, provider)
+        resolved_id = resolve_provider_registry_id(resolved_id, provider, config)
+        index = models_by_id
+        Array(index[resolved_id]).find { |m| m.provider == provider.to_s } ||
+          Array(index[model_id]).find { |m| m.provider == provider.to_s } ||
+          raise_model_not_found(model_id, provider: provider)
+      end
+
+      def resolve_provider_registry_id(model_id, provider, config = nil)
+        provider_class = Provider.resolve(provider)
+        return model_id unless provider_class
+
+        provider_class.resolve_registry_id(model_id, self, config || RubyLLM.config)
+      end
+
+      # A name can be one provider's exact id and another's alias:
+      # claude-opus-4 is exact on vertexai, an alias on anthropic.
+      # Provider preference settles it, not the kind of match.
+      def find_without_provider(model_id)
+        resolved_id = Aliases.resolve(model_id)
+        index = models_by_id
+        matches = Array(index[model_id])
+        matches += Array(index[resolved_id]) unless resolved_id == model_id
+
+        preferred_match(matches) || raise_model_not_found(model_id)
+      end
+
+      def raise_model_not_found(model_id, provider: nil)
+        message = "Unknown model: #{model_id.inspect}"
+        message = "#{message} for provider: #{provider.inspect}" if provider
+
+        raise ModelNotFoundError, "#{message}. #{refresh_registry_guidance}"
+      end
+
+      def refresh_registry_guidance
+        'If the model exists at the provider, refresh the registry with `RubyLLM.models.refresh`.'
+      end
+
+      def preferred_match(candidates)
+        return candidates.first if candidates.size == 1
+
+        candidates.min_by do |model|
+          index = PROVIDER_PREFERENCE.index(model.provider)
+          [model.unlisted? ? 1 : 0, index || PROVIDER_PREFERENCE.length]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/models/registry.rb

@@ -94,7 +94,7 @@ module RubyLLM
 
         def fetch(etag: nil)
           connection = RubyLLM::Transport::Connection.basic do |faraday|
-            faraday.response :json, parser_options: { symbolize_names: true }
+            faraday.use Transport::JsonResponse, parser_options: { symbolize_names: true }
           end
           response = connection.get(url) do |request|
             request.headers['If-None-Match'] = etag if etag
@@ -116,7 +116,7 @@ module RubyLLM
       module_function
 
       def read(file)
-        data = JSON.parse(File.read(file), symbolize_names: true)
+        data = JSON.parse(File.read(file, encoding: Encoding::UTF_8), symbolize_names: true)
         models_from_data(data, source: file)
       rescue Errno::ENOENT
         nil

data/lib/ruby_llm/models/schema.rb

@@ -13,7 +13,7 @@ module RubyLLM
         structured_output predicted_outputs
         distillation fine_tuning batch realtime image_generation
         speech_generation transcription translation citations reasoning
-        caching moderation json_mode vision video ocr
+        caching moderation json_mode vision video ocr judgment
       ].freeze
 
       description 'A model entry in the RubyLLM model registry'