ruby_llm 1.14.0 → 1.15.0

data/lib/ruby_llm/providers/openrouter/chat.rb

@@ -60,8 +60,7 @@ module RubyLLM
           return unless message_data
 
           usage = data['usage'] || {}
-          cached_tokens = usage.dig('prompt_tokens_details', 'cached_tokens')
-          thinking_tokens = usage.dig('completion_tokens_details', 'reasoning_tokens')
+          thinking_tokens = thinking_tokens(usage)
           thinking_text = extract_thinking_text(message_data)
           thinking_signature = extract_thinking_signature(message_data)
 
@@ -70,16 +69,41 @@ module RubyLLM
             content: message_data['content'],
             thinking: Thinking.build(text: thinking_text, signature: thinking_signature),
             tool_calls: OpenAI::Tools.parse_tool_calls(message_data['tool_calls']),
-            input_tokens: usage['prompt_tokens'],
-            output_tokens: usage['completion_tokens'],
-            cached_tokens: cached_tokens,
-            cache_creation_tokens: 0,
+            input_tokens: input_tokens(usage),
+            output_tokens: output_tokens(usage),
+            cached_tokens: cache_read_tokens(usage),
+            cache_creation_tokens: cache_write_tokens(usage),
             thinking_tokens: thinking_tokens,
             model_id: data['model'],
             raw: response
           )
         end
 
+        def input_tokens(usage)
+          return usage['prompt_cache_miss_tokens'] if usage['prompt_cache_miss_tokens']
+
+          prompt_tokens = usage['prompt_tokens']
+          return unless prompt_tokens
+
+          [prompt_tokens.to_i - cache_read_tokens(usage).to_i - cache_write_tokens(usage).to_i, 0].max
+        end
+
+        def output_tokens(usage)
+          OpenAI::Chat.output_tokens(usage)
+        end
+
+        def cache_read_tokens(usage)
+          usage.dig('prompt_tokens_details', 'cached_tokens') || usage['prompt_cache_hit_tokens']
+        end
+
+        def cache_write_tokens(usage)
+          usage.dig('prompt_tokens_details', 'cache_write_tokens') || 0
+        end
+
+        def thinking_tokens(usage)
+          OpenAI::Chat.thinking_tokens(usage)
+        end
+
         def format_messages(messages)
           messages.map do |msg|
             {

data/lib/ruby_llm/providers/openrouter/images.rb

@@ -9,11 +9,11 @@ module RubyLLM
       module Images
         module_function
 
-        def images_url
+        def images_url(with: nil, mask: nil) # rubocop:disable Lint/UnusedMethodArgument
           'chat/completions'
         end
 
-        def render_image_payload(prompt, model:, size:)
+        def render_image_payload(prompt, model:, size:, with: nil, mask: nil, params: {}) # rubocop:disable Lint/UnusedMethodArgument,Metrics/ParameterLists
           RubyLLM.logger.debug { "Ignoring size #{size}. OpenRouter image generation does not support size parameter." }
           {
             model: model,

data/lib/ruby_llm/providers/openrouter/models.rb

@@ -23,7 +23,7 @@ module RubyLLM
             pricing_types = {
               prompt: :input_per_million,
               completion: :output_per_million,
-              input_cache_read: :cached_input_per_million,
+              input_cache_read: :cache_read_input_per_million,
               internal_reasoning: :reasoning_output_per_million
             }
 

data/lib/ruby_llm/providers/openrouter/streaming.rb

@@ -13,7 +13,6 @@ module RubyLLM
 
         def build_chunk(data)
           usage = data['usage'] || {}
-          cached_tokens = usage.dig('prompt_tokens_details', 'cached_tokens')
           delta = data.dig('choices', 0, 'delta') || {}
 
           Chunk.new(
@@ -25,11 +24,11 @@ module RubyLLM
               signature: extract_thinking_signature(delta)
             ),
             tool_calls: OpenAI::Tools.parse_tool_calls(delta['tool_calls'], parse_arguments: false),
-            input_tokens: usage['prompt_tokens'],
-            output_tokens: usage['completion_tokens'],
-            cached_tokens: cached_tokens,
-            cache_creation_tokens: 0,
-            thinking_tokens: usage.dig('completion_tokens_details', 'reasoning_tokens')
+            input_tokens: OpenRouter::Chat.input_tokens(usage),
+            output_tokens: OpenRouter::Chat.output_tokens(usage),
+            cached_tokens: OpenRouter::Chat.cache_read_tokens(usage),
+            cache_creation_tokens: OpenRouter::Chat.cache_write_tokens(usage),
+            thinking_tokens: OpenRouter::Chat.thinking_tokens(usage)
           )
         end
 

data/lib/ruby_llm/providers/perplexity/capabilities.rb

@@ -3,63 +3,55 @@
 module RubyLLM
   module Providers
     class Perplexity
-      # Determines capabilities and pricing for Perplexity models
+      # Provider-level capability checks and narrow registry fallbacks.
       module Capabilities
         module_function
 
-        def context_window_for(model_id)
-          case model_id
-          when /sonar-pro/ then 200_000
-          else 128_000
-          end
-        end
+        PRICES = {
+          sonar: { input: 1.0, output: 1.0 },
+          sonar_pro: { input: 3.0, output: 15.0 },
+          sonar_reasoning: { input: 1.0, output: 5.0 },
+          sonar_reasoning_pro: { input: 2.0, output: 8.0 },
+          sonar_deep_research: {
+            input: 2.0,
+            output: 8.0,
+            reasoning_output: 3.0
+          }
+        }.freeze
 
-        def max_tokens_for(model_id)
-          case model_id
-          when /sonar-(?:pro|reasoning-pro)/ then 8_192
-          else 4_096
-          end
+        def supports_tool_choice?(_model_id)
+          false
         end
 
-        def input_price_for(model_id)
-          PRICES.dig(model_family(model_id), :input) || 1.0
+        def supports_tool_parallel_control?(_model_id)
+          false
         end
 
-        def output_price_for(model_id)
-          PRICES.dig(model_family(model_id), :output) || 1.0
+        def context_window_for(model_id)
+          model_id.match?(/sonar-pro/) ? 200_000 : 128_000
         end
 
-        def supports_vision?(model_id)
-          case model_id
-          when /sonar-reasoning-pro/, /sonar-reasoning/, /sonar-pro/, /sonar/ then true
-          else false
-          end
+        def max_tokens_for(model_id)
+          model_id.match?(/sonar-(?:pro|reasoning-pro)/) ? 8_192 : 4_096
         end
 
-        def supports_functions?(_model_id)
-          false
+        def critical_capabilities_for(model_id)
+          capabilities = []
+          capabilities << 'vision' if model_id.match?(/sonar(?:-pro|-reasoning(?:-pro)?)?$/)
+          capabilities << 'reasoning' if model_id.match?(/reasoning|deep-research/)
+          capabilities
         end
 
-        def supports_json_mode?(_model_id)
-          true
-        end
+        def pricing_for(model_id)
+          prices = PRICES.fetch(model_family(model_id), { input: 1.0, output: 1.0 })
 
-        def format_display_name(model_id)
-          case model_id
-          when 'sonar' then 'Sonar'
-          when 'sonar-pro' then 'Sonar Pro'
-          when 'sonar-reasoning' then 'Sonar Reasoning'
-          when 'sonar-reasoning-pro' then 'Sonar Reasoning Pro'
-          when 'sonar-deep-research' then 'Sonar Deep Research'
-          else
-            model_id.split('-')
-                    .map(&:capitalize)
-                    .join(' ')
-          end
-        end
+          standard = {
+            input_per_million: prices[:input],
+            output_per_million: prices[:output]
+          }
+          standard[:reasoning_output_per_million] = prices[:reasoning_output] if prices[:reasoning_output]
 
-        def model_type(_model_id)
-          'chat'
+          { text_tokens: { standard: standard } }
         end
 
         def model_family(model_id)
@@ -73,64 +65,7 @@ module RubyLLM
           end
         end
 
-        def modalities_for(_model_id)
-          {
-            input: ['text'],
-            output: ['text']
-          }
-        end
-
-        def capabilities_for(model_id)
-          capabilities = %w[streaming json_mode]
-          capabilities << 'vision' if supports_vision?(model_id)
-          capabilities
-        end
-
-        def pricing_for(model_id)
-          family = model_family(model_id)
-          prices = PRICES.fetch(family, { input: 1.0, output: 1.0 })
-
-          standard_pricing = {
-            input_per_million: prices[:input],
-            output_per_million: prices[:output]
-          }
-
-          standard_pricing[:citation_per_million] = prices[:citation] if prices[:citation]
-          standard_pricing[:reasoning_per_million] = prices[:reasoning] if prices[:reasoning]
-          standard_pricing[:search_per_thousand] = prices[:search_queries] if prices[:search_queries]
-
-          {
-            text_tokens: {
-              standard: standard_pricing
-            }
-          }
-        end
-
-        PRICES = {
-          sonar: {
-            input: 1.0,
-            output: 1.0
-          },
-          sonar_pro: {
-            input: 3.0,
-            output: 15.0
-          },
-          sonar_reasoning: {
-            input: 1.0,
-            output: 5.0
-          },
-          sonar_reasoning_pro: {
-            input: 2.0,
-            output: 8.0
-          },
-          sonar_deep_research: {
-            input: 2.0,
-            output: 8.0,
-            citation: 2.0,
-            reasoning: 3.0,
-            search_queries: 5.0
-          }
-        }.freeze
+        module_function :context_window_for, :max_tokens_for, :critical_capabilities_for, :pricing_for, :model_family
       end
     end
   end

data/lib/ruby_llm/providers/perplexity/models.rb

@@ -5,33 +5,31 @@ module RubyLLM
     class Perplexity
       # Models methods of the Perplexity API integration
       module Models
+        MODEL_IDS = %w[
+          sonar
+          sonar-pro
+          sonar-reasoning
+          sonar-reasoning-pro
+          sonar-deep-research
+        ].freeze
+
         def list_models(**)
           slug = 'perplexity'
-          capabilities = Perplexity::Capabilities
-          parse_list_models_response(nil, slug, capabilities)
+          parse_list_models_response(nil, slug, Perplexity::Capabilities)
         end
 
         def parse_list_models_response(_response, slug, capabilities)
-          [
-            create_model_info('sonar', slug, capabilities),
-            create_model_info('sonar-pro', slug, capabilities),
-            create_model_info('sonar-reasoning', slug, capabilities),
-            create_model_info('sonar-reasoning-pro', slug, capabilities),
-            create_model_info('sonar-deep-research', slug, capabilities)
-          ]
+          MODEL_IDS.map { |id| create_model_info(id, slug, capabilities) }
         end
 
         def create_model_info(id, slug, capabilities)
           Model::Info.new(
             id: id,
-            name: capabilities.format_display_name(id),
+            name: id,
             provider: slug,
-            family: capabilities.model_family(id).to_s,
-            created_at: Time.now,
             context_window: capabilities.context_window_for(id),
             max_output_tokens: capabilities.max_tokens_for(id),
-            modalities: capabilities.modalities_for(id),
-            capabilities: capabilities.capabilities_for(id),
+            capabilities: capabilities.critical_capabilities_for(id),
             pricing: capabilities.pricing_for(id),
             metadata: {}
           )

data/lib/ruby_llm/railtie.rb

@@ -12,6 +12,12 @@ if defined?(Rails::Railtie)
 
       initializer 'ruby_llm.active_record' do
         ActiveSupport.on_load :active_record do
+          require 'ruby_llm/active_record/payload_helpers'
+          require 'ruby_llm/active_record/chat_methods'
+          require 'ruby_llm/active_record/message_methods'
+          require 'ruby_llm/active_record/model_methods'
+          require 'ruby_llm/active_record/tool_call_methods'
+
           if RubyLLM.config.use_new_acts_as
             require 'ruby_llm/active_record/acts_as'
             ::ActiveRecord::Base.include RubyLLM::ActiveRecord::ActsAs

data/lib/ruby_llm/tokens.rb

@@ -43,5 +43,13 @@ module RubyLLM
     def reasoning
       thinking
     end
+
+    def cache_read
+      cached
+    end
+
+    def cache_write
+      cache_creation
+    end
   end
 end

data/lib/ruby_llm/tool.rb

@@ -7,10 +7,10 @@ module RubyLLM
   class Parameter
     attr_reader :name, :type, :description, :required
 
-    def initialize(name, type: 'string', desc: nil, required: true)
+    def initialize(name, type: 'string', desc: nil, description: nil, required: true)
       @name = name
       @type = type
-      @description = desc
+      @description = desc || description
       @required = required
     end
   end
@@ -30,6 +30,8 @@ module RubyLLM
       end
     end
 
+    POSITIONAL_PARAMETER_KINDS = %i[req opt rest].freeze
+
     class << self
       attr_reader :params_schema_definition
 
@@ -38,6 +40,7 @@ module RubyLLM
 
         @description = text
       end
+      alias desc description
 
       def param(name, **options)
         parameters[name] = Parameter.new(name, **options)
@@ -94,6 +97,8 @@ module RubyLLM
           definition.json_schema
         elsif parameters.any?
           SchemaDefinition.from_parameters(parameters)&.json_schema
+        else
+          SchemaDefinition.from_parameters(inferred_parameters, allow_empty: true)&.json_schema
         end
       end
     end
@@ -127,9 +132,10 @@ module RubyLLM
     end
 
     def validate_keyword_arguments(arguments)
-      required_keywords, optional_keywords, accepts_extra_keywords = execute_keyword_signature
+      required_keywords, optional_keywords, accepts_extra_keywords, accepts_positional_arguments =
+        execute_keyword_signature
 
-      return nil if required_keywords.empty? && optional_keywords.empty?
+      return nil if required_keywords.empty? && optional_keywords.empty? && accepts_positional_arguments
 
       argument_keys = arguments.keys
       missing_keyword = first_missing_keyword(required_keywords, argument_keys)
@@ -148,8 +154,11 @@ module RubyLLM
       required_keywords = keyword_signature.filter_map { |kind, name| name if kind == :keyreq }
       optional_keywords = keyword_signature.filter_map { |kind, name| name if kind == :key }
       accepts_extra_keywords = keyword_signature.any? { |kind, _| kind == :keyrest }
+      accepts_positional_arguments = keyword_signature.any? do |kind, _|
+        POSITIONAL_PARAMETER_KINDS.include?(kind)
+      end
 
-      [required_keywords, optional_keywords, accepts_extra_keywords]
+      [required_keywords, optional_keywords, accepts_extra_keywords, accepts_positional_arguments]
     end
 
     def first_missing_keyword(required_keywords, argument_keys)
@@ -160,11 +169,19 @@ module RubyLLM
       (argument_keys - allowed_keywords).first
     end
 
+    def inferred_parameters
+      required_keywords, optional_keywords, = execute_keyword_signature
+
+      (required_keywords + optional_keywords).to_h do |name|
+        [name, Parameter.new(name, required: required_keywords.include?(name))]
+      end
+    end
+
     # Wraps schema handling for tool parameters, supporting JSON Schema hashes,
     # RubyLLM::Schema instances/classes, and DSL blocks.
     class SchemaDefinition
-      def self.from_parameters(parameters)
-        return nil if parameters.nil? || parameters.empty?
+      def self.from_parameters(parameters, allow_empty: false)
+        return nil if parameters.nil? || (parameters.empty? && !allow_empty)
 
         properties = parameters.to_h do |name, param|
           schema = {

data/lib/ruby_llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  VERSION = '1.14.0'
+  VERSION = '1.15.0'
 end

data/lib/ruby_llm.rb

@@ -33,6 +33,7 @@ loader.inflector.inflect(
 )
 loader.ignore("#{__dir__}/tasks")
 loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/ruby_llm/active_record")
 loader.ignore("#{__dir__}/ruby_llm/railtie.rb")
 loader.setup
 
@@ -107,7 +108,4 @@ RubyLLM::Provider.register :perplexity, RubyLLM::Providers::Perplexity
 RubyLLM::Provider.register :vertexai, RubyLLM::Providers::VertexAI
 RubyLLM::Provider.register :xai, RubyLLM::Providers::XAI
 
-if defined?(Rails::Railtie)
-  require 'ruby_llm/railtie'
-  require 'ruby_llm/active_record/acts_as'
-end
+require 'ruby_llm/railtie' if defined?(Rails::Railtie)

data/lib/tasks/models.rake

@@ -329,22 +329,23 @@ end
 
 def standard_pricing_display(model)
   pricing_data = model.pricing.to_h[:text_tokens]&.dig(:standard) || {}
+  parts = [
+    pricing_part(pricing_data, :input_per_million, 'In'),
+    pricing_part(pricing_data, :output_per_million, 'Out'),
+    pricing_part(pricing_data, %i[cache_read_input_per_million cached_input_per_million], 'Cache Read'),
+    pricing_part(pricing_data, %i[cache_write_input_per_million cache_creation_input_per_million], 'Cache Write')
+  ].compact
 
-  if pricing_data.any?
-    parts = []
+  return parts.join(', ') if parts.any?
 
-    parts << "In: $#{format('%.2f', pricing_data[:input_per_million])}" if pricing_data[:input_per_million]
-
-    parts << "Out: $#{format('%.2f', pricing_data[:output_per_million])}" if pricing_data[:output_per_million]
-
-    if pricing_data[:cached_input_per_million]
-      parts << "Cache: $#{format('%.2f', pricing_data[:cached_input_per_million])}"
-    end
+  '-'
+end
 
-    return parts.join(', ') if parts.any?
-  end
+def pricing_part(pricing_data, key, label)
+  key = Array(key).find { |candidate| pricing_data[candidate] }
+  return unless key
 
-  '-'
+  "#{label}: $#{format('%.2f', pricing_data[key])}"
 end
 
 def generate_aliases # rubocop:disable Metrics/PerceivedComplexity

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm
 version: !ruby/object:Gem::Version
-  version: 1.14.0
+  version: 1.15.0
 platform: ruby
 authors:
 - Carmine Paolino
@@ -228,6 +228,7 @@ files:
 - lib/ruby_llm/active_record/chat_methods.rb
 - lib/ruby_llm/active_record/message_methods.rb
 - lib/ruby_llm/active_record/model_methods.rb
+- lib/ruby_llm/active_record/payload_helpers.rb
 - lib/ruby_llm/active_record/tool_call_methods.rb
 - lib/ruby_llm/agent.rb
 - lib/ruby_llm/aliases.json
@@ -239,6 +240,7 @@ files:
 - lib/ruby_llm/connection.rb
 - lib/ruby_llm/content.rb
 - lib/ruby_llm/context.rb
+- lib/ruby_llm/cost.rb
 - lib/ruby_llm/embedding.rb
 - lib/ruby_llm/error.rb
 - lib/ruby_llm/image.rb
@@ -353,14 +355,28 @@ licenses:
 metadata:
   homepage_uri: https://rubyllm.com
   source_code_uri: https://github.com/crmne/ruby_llm
-  changelog_uri: https://github.com/crmne/ruby_llm/commits/main
+  changelog_uri: https://github.com/crmne/ruby_llm/releases
   documentation_uri: https://rubyllm.com
   bug_tracker_uri: https://github.com/crmne/ruby_llm/issues
   funding_uri: https://github.com/sponsors/crmne
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Upgrading from RubyLLM < 1.14.x? Check the upgrade guide for new features and migration instructions
-  --> https://rubyllm.com/upgrading/
+  RubyLLM 1.15 upgrade note:
+
+    Token accounting is now normalized across providers. `input_tokens` means
+    standard input tokens; prompt cache reads and writes are exposed separately
+    as `cache_read_tokens` and `cache_write_tokens`.
+
+    Need request-side input activity?
+      input_tokens + cache_read_tokens + cache_write_tokens
+
+    New cost helpers:
+      response.cost.total
+      chat.cost.total
+      agent.cost.total
+
+    Upgrading from RubyLLM < 1.15? Read the full upgrade guide:
+      https://rubyllm.com/upgrading/
 rdoc_options: []
 require_paths:
 - lib
@@ -375,7 +391,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: One beautiful Ruby API for GPT, Claude, Gemini, and more.
 test_files: []