ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/message.rb

@@ -1,127 +1,306 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # A single message in a chat conversation.
+  # A Message is a single entry in a chat conversation: a user prompt, an
+  # assistant reply, a system instruction, or a tool result. Chat#ask
+  # returns the model's reply as a Message, and Chat#messages holds the
+  # transcript as an array of them.
+  #
+  #   response = chat.ask "What is the capital of France?"
+  #   response.role          # => :assistant
+  #   response.content       # => "The capital of France is Paris."
+  #   response.finish_reason # => :stop
+  #
+  # A Message also carries everything else the provider returned: token
+  # usage (#tokens), reasoning output (#thinking), source citations
+  # (#citations), and requested tool calls (#tool_calls).
   class Message
+    include Support::Inspectable
+    include Accounting::Usage::Result
+
+    # The valid message roles: +:system+, +:user+, +:assistant+, and +:tool+.
     ROLES = %i[system user assistant tool].freeze
 
-    attr_reader :role, :model_id, :tool_calls, :tool_call_id, :raw, :thinking, :tokens
-    attr_writer :content
+    # The role of the message: +:system+, +:user+, +:assistant+, or +:tool+.
+    attr_reader :role
+
+    # The message text as a String. Empty for assistant messages that only
+    # request tool calls.
+    attr_reader :content
+
+    # The files sent or returned with the message, as an array of
+    # Attachment objects.
+    attr_reader :attachments
+
+    # The ID of the model that produced the message, +nil+ on user messages.
+    attr_reader :model
+
+    # The tool calls the assistant requested, as a Hash of ToolCall objects
+    # keyed by call ID, or +nil+.
+    attr_reader :tool_calls
+
+    # The ID of the tool call this message answers. Set only on tool result
+    # messages.
+    attr_reader :tool_call_id
+
+    # The raw provider response: a Faraday::Response, or the result body
+    # Hash for messages retrieved from a Batch.
+    attr_reader :raw
+
+    # The model's reasoning output as a Thinking object, or +nil+ when the
+    # provider returned none.
+    attr_reader :thinking
+
+    # The source citations as an array of Citation objects, normalized
+    # across providers.
+    attr_reader :citations
+
+    # Why the model stopped: +:stop+, +:max_tokens+, +:tool_calls+, or
+    # +:content_filter+. Any other reason comes through as the provider
+    # spelled it, such as Anthropic's +:pause_turn+.
+    attr_reader :finish_reason
+
+    # The provider-executed tool steps in this response, as an array of
+    # ServerToolCall objects. Empty unless the chat enabled tools with
+    # Chat#with_server_tools and the model used one.
+    attr_reader :server_tool_calls
+
+    # 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.
+    attr_reader :raw_content # :nodoc:
 
-    def initialize(options = {})
+    # The provider-shaped reasoning payload of this assistant message, kept
+    # verbatim so later requests can replay the model's reasoning exactly.
+    # +nil+ when the provider returned none.
+    attr_reader :raw_reasoning # :nodoc:
+
+    # The Chat this message belongs to, set when it is added to a
+    # conversation. Backs #tool_results.
+    attr_accessor :conversation # :nodoc:
+
+    def initialize(options = {}) # :nodoc:
       @role = options.fetch(:role).to_sym
-      @tool_calls = options[:tool_calls]
-      @content = normalize_content(options.fetch(:content), role: @role, tool_calls: @tool_calls)
-      @model_id = options[:model_id]
+      @tool_calls = coerce_tool_calls(options[:tool_calls])
+      @content = normalize_content(options.fetch(:content))
+      @config = options[:config]
+      @attachments = Attachment.wrap(options[:attachments], config: @config)
+      @model = options[:model]
+      @supplied_cost = coerce_value(options[:cost], Cost)
       @tool_call_id = options[:tool_call_id]
-      @tokens = options[:tokens] || Tokens.build(
+      @tokens = options[:tokens] || Tokens.new(
         input: options[:input_tokens],
         output: options[:output_tokens],
-        cached: options[:cached_tokens],
-        cache_creation: options[:cache_creation_tokens],
+        cache_read: options[:cache_read_tokens],
+        cache_write: options[:cache_write_tokens],
         thinking: options[:thinking_tokens],
-        reasoning: options[:reasoning_tokens]
+        server_tool_use: options[:server_tool_use],
+        reported_cost: options[:reported_cost]
       )
       @raw = options[:raw]
-      @thinking = options[:thinking]
+      @thinking = coerce_thinking(options[:thinking], options[:thinking_signature])
+      @citations = Array(options[:citations]).map { |citation| coerce_value(citation, Citation) }
+      @server_tool_calls = Array(options[:server_tool_calls]).map { |call| coerce_value(call, ServerToolCall) }
+      @raw_content = options[:raw_content]
+      @raw_reasoning = options[:raw_reasoning]
+      @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)
 
       ensure_valid_role
     end
 
-    def content
-      if @content.is_a?(Content) && @content.text && @content.attachments.empty?
-        @content.text
-      else
-        @content
-      end
+    # Returns #content parsed as JSON, memoized after the first call.
+    # Useful for reading structured output responses.
+    #
+    #   response = chat.with_schema(PersonSchema).ask "Generate a person"
+    #   response.parsed # => {"name" => "Alice", "age" => 30}
+    #
+    def parsed
+      return if content.nil? || content.empty?
+
+      @parsed ||= JSON.parse(content)
+    end
+
+    def with_attachments(attachments) # :nodoc:
+      wrapped = Attachment.wrap(attachments, config: @config)
+      dup.tap { |message| message.instance_variable_set(:@attachments, wrapped) }
     end
 
+    # Returns +true+ if the assistant requested one or more tool calls,
+    # +false+ otherwise.
     def tool_call?
       !tool_calls.nil? && !tool_calls.empty?
     end
 
+    # Returns +true+ if the message carries the result of a tool call,
+    # +false+ otherwise.
     def tool_result?
       !tool_call_id.nil? && !tool_call_id.empty?
     end
 
+    # Returns the tool result messages answering this message's tool calls,
+    # or an empty array when it made none. Mirrors the +tool_results+
+    # association on acts_as_message records.
     def tool_results
-      content if tool_result?
-    end
+      return [] unless tool_call? && conversation
 
-    def input_tokens
-      tokens&.input
+      conversation.messages.select do |message|
+        message.tool_result? && tool_calls.key?(message.tool_call_id)
+      end
     end
 
-    def output_tokens
-      tokens&.output
+    # Returns +true+ if #finish_reason indicates the model finished
+    # normally, +false+ otherwise. A turn that stopped to call tools is
+    # reported by #tool_call_stop? instead, whatever the provider named it.
+    def stopped?
+      finish_reason == :stop && !tool_call?
     end
 
-    def cached_tokens
-      tokens&.cached
+    # Returns +true+ if the response was cut off by a token limit,
+    # +false+ otherwise.
+    def max_tokens?
+      finish_reason == :max_tokens
     end
 
-    def cache_creation_tokens
-      tokens&.cache_creation
+    # Returns +true+ if the model stopped to request tool calls,
+    # +false+ otherwise.
+    def tool_call_stop?
+      finish_reason == :tool_calls || (tool_call? && finish_reason == :stop)
     end
 
-    def cache_read_tokens
-      tokens&.cache_read
+    # Returns +true+ if a provider safety filter stopped the response,
+    # +false+ otherwise.
+    def content_filtered?
+      finish_reason == :content_filter
     end
 
-    def cache_write_tokens
-      tokens&.cache_write
+    # Returns usage aggregated across every provider attempt that produced this
+    # message. Messages constructed by hand report the token counts they were
+    # built with.
+    def tokens
+      return @tokens if ruby_llm_usage_entries.empty?
+
+      ruby_llm_usage_tokens
     end
 
-    def thinking_tokens
-      tokens&.thinking
+    # Returns a Cost pricing this message's token usage in US dollars.
+    # Uses recorded attempt costs, an explicitly supplied +cost:+, or pricing
+    # from #model_info. An explicit +model:+ overrides those costs for repricing.
+    #
+    #   response.cost.total
+    #
+    def cost(model: nil)
+      return ruby_llm_usage_cost if model.nil? && ruby_llm_usage_entries.any?
+      return @supplied_cost if model.nil? && @supplied_cost
+
+      Cost.new(tokens:, model: model || model_info)
     end
 
-    def reasoning_tokens
-      tokens&.thinking
+    # 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+.
+    #
+    #   chat.add_message(role: :user, content: long_context).cache_until_here
+    #
+    def cache_until_here
+      @cache_until_here = true
+      self
     end
 
-    def cost(model: nil)
-      Cost.new(tokens:, model: model || model_info)
+    # Returns +true+ if the message carries an explicit prompt cache
+    # boundary, +false+ otherwise.
+    def cache_until_here?
+      @cache_until_here
     end
 
+    # 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.
     def to_h
       {
         role: role,
         content: content,
-        model_id: model_id,
-        tool_calls: tool_calls,
+        attachments: list_to_h(attachments),
+        model: model,
+        cost: @supplied_cost && cost.to_h,
+        tool_calls: tool_calls&.transform_values(&:to_h),
         tool_call_id: tool_call_id,
         thinking: thinking&.text,
-        thinking_signature: thinking&.signature
-      }.merge(tokens ? tokens.to_h : {}).compact
-    end
-
-    def instance_variables
-      super - [:@raw]
+        thinking_signature: thinking&.signature,
+        citations: list_to_h(citations),
+        server_tool_calls: list_to_h(server_tool_calls),
+        raw_content: raw_content,
+        raw_reasoning: raw_reasoning,
+        finish_reason: finish_reason,
+        cache_until_here: cache_until_here? || nil
+      }.merge(tokens.to_h).compact
     end
 
+    # Returns the Model record for #model from the model registry, or
+    # +nil+ when the message has no model or the model is unknown.
     def model_info
-      return unless model_id
+      return unless model
 
-      @model_info ||= RubyLLM.models.find(model_id)
+      @model_info ||= RubyLLM.models.find(model)
     rescue ModelNotFoundError
       nil
     end
 
     private
 
-    def normalize_content(content, role:, tool_calls:)
-      return '' if role == :assistant && content.nil? && tool_calls && !tool_calls.empty?
+    def list_to_h(list)
+      list.empty? ? nil : list.map(&:to_h)
+    end
 
-      case content
-      when String then Content.new(content)
-      when Hash then Content.new(content[:text], content)
-      else content
+    def coerce_tool_calls(tool_calls)
+      return tool_calls unless tool_calls.is_a?(Hash)
+
+      tool_calls.to_h do |id, call|
+        next [id, call] unless call.is_a?(Hash)
+
+        attributes = call.transform_keys(&:to_sym)
+        [id, ToolCall.new(id: attributes[:id] || id, name: attributes[:name],
+                          arguments: attributes[:arguments] || {},
+                          thought_signature: attributes[:thought_signature], remote: attributes.fetch(:remote, false))]
+      end
+    end
+
+    def coerce_thinking(thinking, signature)
+      case thinking
+      when nil, Thinking then thinking
+      when Hash then Thinking.build(**thinking.transform_keys(&:to_sym).slice(:text, :signature))
+      else Thinking.build(text: thinking.to_s, signature: signature)
       end
     end
 
+    def coerce_value(value, klass)
+      value.is_a?(Hash) ? klass.from_h(value) : 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)
+
+      raise ArgumentError,
+            "Message content must be a String, got #{content.class}. " \
+            'Pass files via attachments: and structured data as JSON.'
+    end
+
     def ensure_valid_role
       raise InvalidRoleError, "Expected role to be one of: #{ROLES.join(', ')}" unless ROLES.include?(role)
     end
+
+    def inspect_attributes # :nodoc:
+      {
+        role: role,
+        content: content,
+        tool_calls: tool_calls&.values&.map(&:name),
+        tool_call_id: tool_call_id,
+        model: model,
+        finish_reason: finish_reason
+      }
+    end
   end
 end

data/lib/ruby_llm/model/modalities.rb

@@ -1,16 +1,29 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  module Model
-    # Holds and manages input and output modalities for a language model
+  class Model
+    # A Model::Modalities lists the kinds of content a model accepts and
+    # produces, as arrays of Strings. Instances come from Model#modalities.
+    #
+    #   model = RubyLLM.models.find('gpt-5.6')
+    #   model.modalities.input   # => ["text", "image", "pdf"]
+    #   model.modalities.output  # => ["text"]
+    #
     class Modalities
-      attr_reader :input, :output
+      # The input modalities as an array of Strings,
+      # e.g. <tt>["text", "image", "pdf"]</tt>.
+      attr_reader :input
 
-      def initialize(data)
+      # The output modalities as an array of Strings,
+      # e.g. <tt>["text"]</tt> or <tt>["embeddings"]</tt>.
+      attr_reader :output
+
+      def initialize(data) # :nodoc:
         @input = Array(data[:input]).map(&:to_s)
         @output = Array(data[:output]).map(&:to_s)
       end
 
+      # Returns the modalities as a Hash with +:input+ and +:output+ keys.
       def to_h
         {
           input: input,

data/lib/ruby_llm/model/pricing.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  module Model
-    # A collection that manages and provides access to different categories of pricing information
+  class Model
+    # A Pricing groups a model's prices by usage category: text tokens,
+    # images, audio tokens, and embeddings. Each category is a
+    # PricingCategory. Prices are in USD per million tokens. Instances come
+    # from Model#pricing.
+    #
+    #   model = RubyLLM.models.find "claude-sonnet-5"
+    #   model.pricing.text_tokens.input   # => 3
+    #   model.pricing.text_tokens.output  # => 15
+    #
     class Pricing
+      # The pricing categories a model may define.
       CATEGORIES = %i[text_tokens images audio_tokens embeddings].freeze
 
-      def initialize(data)
+      def initialize(data) # :nodoc:
         @data = {}
 
         CATEGORIES.each do |category|
@@ -14,22 +23,32 @@ module RubyLLM
         end
       end
 
+      # Returns the PricingCategory for text token prices, or an empty
+      # category if the model has none.
       def text_tokens
         category(:text_tokens)
       end
 
+      # Returns the PricingCategory for image generation prices, or an empty
+      # category if the model has none.
       def images
         category(:images)
       end
 
+      # Returns the PricingCategory for audio token prices, or an empty
+      # category if the model has none.
       def audio_tokens
         category(:audio_tokens)
       end
 
+      # Returns the PricingCategory for embedding prices, or an empty
+      # category if the model has none.
       def embeddings
         category(:embeddings)
       end
 
+      # Returns the pricing data as a nested Hash keyed by category.
+      # Categories without prices are omitted.
       def to_h
         @data.transform_values(&:to_h)
       end
@@ -43,11 +62,11 @@ module RubyLLM
       def empty_pricing?(data)
         return true unless data
 
-        %i[standard batch].each do |tier|
+        PricingCategory::TIERS.each do |tier|
           next unless data[tier]
 
           data[tier].each_value do |value|
-            return false if value && value != 0.0
+            return false unless value.nil?
           end
         end
 

data/lib/ruby_llm/model/pricing_category.rb

@@ -1,56 +1,145 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  module Model
-    # Represents pricing tiers for different usage categories (standard and batch)
+  class Model
+    # A PricingCategory holds the standard, batch, and long-context pricing
+    # tiers for one kind of model usage, such as text tokens or images.
+    # Model#pricing returns a Pricing collection whose categories are
+    # PricingCategory instances. Prices are in USD per million tokens.
+    #
+    #   model    = RubyLLM.models.find "claude-sonnet-5"
+    #   category = model.pricing.text_tokens
+    #   category.input  # => 3
+    #   category.output # => 15
+    #
     class PricingCategory
-      attr_reader :standard, :batch
+      # The billing tiers a category may define.
+      TIERS = %i[standard batch long_context].freeze
 
-      def initialize(data = {})
-        @standard = PricingTier.new(data[:standard] || {}) unless empty_tier?(data[:standard])
-        @batch = PricingTier.new(data[:batch] || {}) unless empty_tier?(data[:batch])
+      # The standard-tier PricingTier, or +nil+ when the model has no
+      # standard pricing for this category.
+      attr_reader :standard
+
+      # The batch-tier PricingTier, or +nil+ when the model has no batch
+      # pricing for this category.
+      attr_reader :batch
+
+      # The long-context PricingTier, or +nil+ when the model has no
+      # separate rates for prompts above #long_context_threshold.
+      attr_reader :long_context
+
+      # Prompt-size threshold (in tokens) above which long-context rates
+      # apply, or +nil+ when the model has no long-context tier.
+      attr_reader :long_context_threshold
+
+      def initialize(data = {}) # :nodoc:
+        data = data.transform_keys(&:to_sym) if data.respond_to?(:transform_keys)
+
+        @standard = tier_from(data[:standard])
+        @batch = tier_from(data[:batch])
+        @long_context = tier_from(data[:long_context])
+        @long_context_threshold = Integer(data[:long_context_threshold], exception: false)
       end
 
+      # Returns the standard-tier input price in USD per million tokens,
+      # or +nil+ if the price is missing.
       def input
         standard&.input_per_million
       end
 
+      # Returns the standard-tier output price in USD per million tokens,
+      # or +nil+ if the price is missing.
       def output
         standard&.output_per_million
       end
 
+      # Returns the standard-tier cache read price in USD per million
+      # tokens, or +nil+ if the price is missing.
       def cache_read_input
-        standard&.cache_read_input_per_million || standard&.cached_input_per_million
+        standard&.cache_read_input_per_million
       end
 
+      # Returns the standard-tier cache write price in USD per million
+      # tokens, or +nil+ if the price is missing.
       def cache_write_input
-        standard&.cache_write_input_per_million || standard&.cache_creation_input_per_million
+        standard&.cache_write_input_per_million
       end
 
+      # Returns the standard-tier reasoning output price in USD per million
+      # tokens, or +nil+ if the price is missing.
       def reasoning_output
         standard&.reasoning_output_per_million
       end
 
-      alias cached_input cache_read_input
-      alias cache_creation_input cache_write_input
-
-      def [](key)
-        key == :batch ? batch : standard
+      # Returns the PricingTier that applies for a prompt of the given size.
+      # Uses #long_context when that tier exists and +prompt_tokens+ is
+      # greater than #long_context_threshold; otherwise returns #standard.
+      def tier_for(prompt_tokens)
+        if long_context && long_context_threshold &&
+           prompt_tokens.to_i > long_context_threshold
+          long_context
+        else
+          standard
+        end
       end
 
+      # Returns a Hash with present tier hashes and optional
+      # +:long_context_threshold+, omitting absent entries.
       def to_h
         result = {}
         result[:standard] = standard.to_h if standard
         result[:batch] = batch.to_h if batch
+        result[:long_context] = long_context.to_h if long_context
+        result[:long_context_threshold] = long_context_threshold if long_context_threshold
         result
       end
 
+      # Builds long-context rates and threshold from a models.dev-style cost
+      # Hash (as stored on Model#metadata under +:cost+). Returns
+      # <tt>[rates_hash, threshold]</tt>, or <tt>[nil, nil]</tt> when the
+      # cost has no context tier.
+      def self.long_context_from_cost(cost) # :nodoc:
+        cost = RubyLLM::Support::Utils.deep_symbolize_keys(cost || {})
+        return [nil, nil] if cost.empty?
+
+        entry, threshold = context_cost(cost)
+        return [nil, nil] unless entry
+
+        rates = {
+          input_per_million: entry[:input],
+          output_per_million: entry[:output],
+          cache_read_input_per_million: entry[:cache_read],
+          cache_write_input_per_million: entry[:cache_write],
+          reasoning_output_per_million: entry[:reasoning]
+        }.compact
+        rates.empty? ? [nil, nil] : [rates, threshold]
+      end
+
+      def self.context_cost(cost) # :nodoc:
+        context_tier = Array(cost[:tiers]).find do |entry|
+          entry.is_a?(Hash) && entry.dig(:tier, :type).to_s == 'context'
+        end
+        if context_tier
+          [context_tier, Integer(context_tier.dig(:tier, :size), exception: false)]
+        elsif cost[:context_over_200k].is_a?(Hash)
+          [cost[:context_over_200k], 200_000]
+        end
+      end
+
+      private_class_method :context_cost
+
       private
 
+      def tier_from(tier_data)
+        return nil if empty_tier?(tier_data)
+
+        PricingTier.new(tier_data || {})
+      end
+
       def empty_tier?(tier_data)
         return true unless tier_data
 
-        tier_data.values.all? { |v| v.nil? || v == 0.0 }
+        tier_data.values.all?(&:nil?)
       end
     end
   end