riffer 0.52.1 → 0.53.0

data/lib/riffer/{config/pricing → catalog}/rates.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-class Riffer::Config::Pricing::Rates
+class Riffer::Catalog::Rates
   attr_reader :input #: Float # @dynamic input
 
   attr_reader :output #: Float # @dynamic output
@@ -11,12 +11,12 @@ class Riffer::Config::Pricing::Rates
   attr_reader :cache_write #: Float? # @dynamic cache_write
 
   #--
-  #: (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
+  #: (input: untyped, output: untyped, ?cache_read: untyped, ?cache_write: untyped) -> void
   def initialize(input:, output:, cache_read: nil, cache_write: nil)
-    @input = input
-    @output = output
-    @cache_read = cache_read
-    @cache_write = cache_write
+    @input = coerce_rate(input, "input")
+    @output = coerce_rate(output, "output")
+    @cache_read = cache_read.nil? ? nil : coerce_rate(cache_read, "cache_read")
+    @cache_write = cache_write.nil? ? nil : coerce_rate(cache_write, "cache_write")
   end
 
   #--
@@ -33,4 +33,19 @@ class Riffer::Config::Pricing::Rates
                   (output_tokens * output)
     per_million / 1_000_000.0
   end
+
+  private
+
+  #--
+  #: (untyped, String) -> Float
+  def coerce_rate(value, attribute)
+    number = value
+    float = value.is_a?(Numeric) ? number.to_f : nil #: Float?
+    unless float&.finite? && float >= 0
+      raise Riffer::ArgumentError,
+            "#{attribute} rate must be a non-negative number, got #{value.inspect}"
+    end
+
+    float
+  end
 end

data/lib/riffer/catalog.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+
+class Riffer::Catalog
+  SUPPORTED_VERSIONS = [1].freeze #: Array[Integer]
+
+  FILE_KEYS = %w[version models].freeze #: Array[String]
+
+  ENTRY_KEYS = %w[aliases pricing reasoning].freeze #: Array[String]
+
+  PRICING_KEYS = %w[input output cache_read cache_write].freeze #: Array[String]
+
+  # @rbs @models: Hash[String, Hash[Symbol, untyped]]
+  # @rbs @aliases: Hash[String, String]
+
+  #--
+  #: (Array[String]) -> Riffer::Catalog
+  def self.load(paths)
+    models = {} #: Hash[String, Hash[Symbol, untyped]]
+    aliases = {} #: Hash[String, String]
+
+    paths.each do |path|
+      parse_file(path).each do |key, entry|
+        layered = models[key] || { aliases: [] }
+        layered = layered.merge(entry.slice(:pricing, :reasoning))
+        layered[:aliases] = layered[:aliases] | entry[:aliases]
+        models[key] = layered
+
+        # A later file wins a claimed alias, so a user file can repoint one.
+        entry[:aliases].each do |alias_key|
+          previous = aliases[alias_key]
+          previous_entry = models[previous] if previous && previous != key
+          previous_entry[:aliases] -= [alias_key] if previous_entry
+          aliases[alias_key] = key
+        end
+      end
+    end
+
+    aliases.each do |alias_key, key|
+      next unless models.key?(alias_key)
+
+      raise Riffer::ArgumentError, "catalog alias #{alias_key.inspect} on #{key.inspect} is also a model key"
+    end
+
+    new(models: models, aliases: aliases)
+  end
+
+  #--
+  #: (models: Hash[String, Hash[Symbol, untyped]], aliases: Hash[String, String]) -> void
+  def initialize(models:, aliases:)
+    @models = deep_freeze(models)
+    @aliases = aliases.dup.freeze
+    freeze
+  end
+
+  #--
+  #: (String, Symbol) -> Hash[Symbol, untyped]?
+  def reasoning_options(key, level)
+    entry(key)&.dig(:reasoning, level)
+  end
+
+  #--
+  #: (String) -> Riffer::Catalog::Rates?
+  def rates_for(key)
+    entry(key)&.dig(:pricing)
+  end
+
+  #--
+  #: () -> bool
+  def empty?
+    @models.empty?
+  end
+
+  #--
+  #: (String) -> Hash[String, Hash[Symbol, untyped]]
+  def self.parse_file(path)
+    data = begin
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError, SystemCallError => e
+      raise Riffer::ArgumentError, "#{path}: cannot load catalog file (#{e.message})"
+    end
+
+    fail_load!(path, "must be a JSON object") unless data.is_a?(Hash)
+    unknown = data.keys - FILE_KEYS
+    fail_load!(path, "unknown keys #{unknown.inspect}; allowed: #{FILE_KEYS.inspect}") unless unknown.empty?
+    unless SUPPORTED_VERSIONS.include?(data["version"])
+      fail_load!(path, "unsupported version #{data['version'].inspect}; supported: #{SUPPORTED_VERSIONS.inspect}")
+    end
+
+    no_models = {} #: Hash[String, untyped]
+    models = data.fetch("models", no_models)
+    fail_load!(path, "models must be an object") unless models.is_a?(Hash)
+
+    claimed = {} #: Hash[String, String]
+    models.to_h do |key, raw|
+      entry = parse_entry(path, key, raw)
+      entry[:aliases].each do |alias_key|
+        if claimed.key?(alias_key)
+          fail_load!(path,
+                     "alias #{alias_key.inspect} is listed by both #{claimed[alias_key].inspect} and #{key.inspect}",)
+        end
+
+        claimed[alias_key] = key
+      end
+      [key, entry]
+    end
+  end
+  private_class_method :parse_file
+
+  #--
+  #: (String, String, untyped) -> Hash[Symbol, untyped]
+  def self.parse_entry(path, key, raw)
+    validate_model_key!(path, key, "model key")
+    fail_load!(path, "#{key}: entry must be an object") unless raw.is_a?(Hash)
+    unknown = raw.keys - ENTRY_KEYS
+    fail_load!(path, "#{key}: unknown keys #{unknown.inspect}; allowed: #{ENTRY_KEYS.inspect}") unless unknown.empty?
+
+    entry = { aliases: parse_aliases(path, key, raw.fetch("aliases", [])) } #: Hash[Symbol, untyped]
+    entry[:pricing] = parse_pricing(path, key, raw["pricing"]) if raw.key?("pricing")
+    entry[:reasoning] = parse_reasoning(path, key, raw["reasoning"]) if raw.key?("reasoning")
+    entry
+  end
+  private_class_method :parse_entry
+
+  #--
+  #: (String, String, untyped) -> Array[String]
+  def self.parse_aliases(path, key, raw)
+    fail_load!(path, "#{key}: aliases must be an array of strings") unless raw.is_a?(Array)
+
+    raw.each { |alias_key| validate_model_key!(path, alias_key, "#{key}: alias") }
+    raw.uniq
+  end
+  private_class_method :parse_aliases
+
+  #--
+  #: (String, String, untyped) -> Riffer::Catalog::Rates
+  def self.parse_pricing(path, key, raw)
+    fail_load!(path, "#{key}: pricing must be an object") unless raw.is_a?(Hash)
+    unknown = raw.keys - PRICING_KEYS
+    unless unknown.empty?
+      fail_load!(path,
+                 "#{key}: unknown pricing keys #{unknown.inspect}; allowed: #{PRICING_KEYS.inspect}",)
+    end
+    missing = %w[input output] - raw.keys
+    fail_load!(path, "#{key}: pricing is missing #{missing.inspect}") unless missing.empty?
+
+    begin
+      Riffer::Catalog::Rates.new(
+        input: raw["input"],
+        output: raw["output"],
+        cache_read: raw["cache_read"],
+        cache_write: raw["cache_write"],
+      )
+    rescue Riffer::ArgumentError => e
+      fail_load!(path, "#{key}: pricing #{e.message}")
+    end
+  end
+  private_class_method :parse_pricing
+
+  #--
+  #: (String, String, untyped) -> Hash[Symbol, Hash[Symbol, untyped]]
+  def self.parse_reasoning(path, key, raw)
+    fail_load!(path, "#{key}: reasoning must be an object") unless raw.is_a?(Hash)
+
+    levels = Riffer::Agent::Config::REASONING_LEVELS
+    raw.to_h do |level, fragment|
+      unless levels.include?(level.to_sym)
+        fail_load!(path, "#{key}: unknown reasoning level #{level.inspect}; allowed: #{levels.map(&:to_s).inspect}")
+      end
+      fail_load!(path, "#{key}: reasoning #{level} must be an object") unless fragment.is_a?(Hash)
+
+      # Symbol keys, so a fragment deep-merges with the caller's model_options.
+      [level.to_sym, symbolize_keys(fragment)]
+    end
+  end
+  private_class_method :parse_reasoning
+
+  #--
+  #: (String, untyped, String) -> void
+  def self.validate_model_key!(path, value, attribute)
+    Riffer::Helpers::Validate.model_id(value, attribute: attribute)
+  rescue Riffer::ArgumentError => e
+    fail_load!(path, e.message)
+  end
+  private_class_method :validate_model_key!
+
+  #--
+  #: (untyped) -> untyped
+  def self.symbolize_keys(value)
+    case value
+    when Hash then value.to_h { |key, entry| [key.to_sym, symbolize_keys(entry)] }
+    when Array then value.map { |entry| symbolize_keys(entry) }
+    else value
+    end
+  end
+  private_class_method :symbolize_keys
+
+  #--
+  #: (String, String) -> bot
+  def self.fail_load!(path, message)
+    raise Riffer::ArgumentError, "#{path}: #{message}"
+  end
+  private_class_method :fail_load!
+
+  private
+
+  #--
+  #: (String) -> Hash[Symbol, untyped]?
+  def entry(key)
+    target = @aliases.fetch(key, key)
+    @models[target]
+  end
+
+  #--
+  #: (untyped) -> untyped
+  def deep_freeze(value)
+    case value
+    when Hash then value.each_value { |entry| deep_freeze(entry) }
+    when Array then value.each { |entry| deep_freeze(entry) }
+    end
+    value.freeze
+  end
+end

data/lib/riffer/config/pricing.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
+# @deprecated Set pricing in a catalog file instead (see docs/CATALOG.md).
+# A catalog entry's pricing wins over rates registered here.
 class Riffer::Config::Pricing
-  # @rbs @rates: Hash[String, Riffer::Config::Pricing::Rates]
+  DEPRECATION_MESSAGE = "riffer: config.pricing is deprecated; move rates into a catalog file " \
+                        "listed in config.catalog_files (see docs/CATALOG.md)" #: String
+
+  # @rbs @rates: Hash[String, Riffer::Catalog::Rates]
+  # @rbs self.@warned: bool
 
   #--
   #: () -> void
@@ -13,22 +19,19 @@ class Riffer::Config::Pricing
   #--
   #: ((String | Array[String]), input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
   def set(models, input:, output:, cache_read: nil, cache_write: nil)
+    self.class.warn_deprecated
+
     ids = models.is_a?(Array) ? models : [models]
     raise Riffer::ArgumentError, "at least one model id is required" if ids.empty?
 
     ids.each { |id| Riffer::Helpers::Validate.model_id(id, attribute: "pricing model id") }
 
-    rates = Rates.new(
-      input: coerce_rate(input, "input"),
-      output: coerce_rate(output, "output"),
-      cache_read: coerce_optional_rate(cache_read, "cache_read"),
-      cache_write: coerce_optional_rate(cache_write, "cache_write"),
-    )
+    rates = Riffer::Catalog::Rates.new(input: input, output: output, cache_read: cache_read, cache_write: cache_write)
     ids.each { |id| @rates[id] = rates }
   end
 
   #--
-  #: (String) -> Riffer::Config::Pricing::Rates?
+  #: (String) -> Riffer::Catalog::Rates?
   def rates_for(model)
     @rates[model]
   end
@@ -39,26 +42,13 @@ class Riffer::Config::Pricing
     @rates.empty?
   end
 
-  private
-
-  #--
-  #: (untyped, String) -> Float
-  def coerce_rate(value, attribute)
-    number = value
-    float = value.is_a?(Numeric) ? number.to_f : nil #: Float?
-    unless float&.finite? && float >= 0
-      raise Riffer::ArgumentError,
-            "#{attribute} rate must be a non-negative number, got #{value.inspect}"
-    end
-
-    float
-  end
-
+  # Once per process, so a boot that sets many models logs one line.
   #--
-  #: (untyped, String) -> Float?
-  def coerce_optional_rate(value, attribute)
-    return nil if value.nil?
+  #: () -> void
+  def self.warn_deprecated
+    return if @warned
 
-    coerce_rate(value, attribute)
+    @warned = true
+    Kernel.warn(DEPRECATION_MESSAGE)
   end
 end

data/lib/riffer/config.rb

@@ -4,6 +4,8 @@
 class Riffer::Config
   VALID_MESSAGE_ID_STRATEGIES = %i[none uuid uuidv7].freeze
 
+  # @rbs @catalog: Riffer::Catalog?
+
   attr_reader :amazon_bedrock #: Riffer::Config::AmazonBedrock # @dynamic amazon_bedrock
 
   attr_reader :anthropic #: Riffer::Config::Anthropic # @dynamic anthropic
@@ -41,8 +43,33 @@ class Riffer::Config
 
   attr_reader :files #: Riffer::Config::Files # @dynamic files
 
+  # @deprecated Use +catalog_files+.
   attr_reader :pricing #: Riffer::Config::Pricing # @dynamic pricing
 
+  attr_reader :catalog_files #: Array[String] # @dynamic catalog_files
+
+  #--
+  #: (Array[untyped]) -> void
+  def catalog_files=(paths)
+    valid = paths.is_a?(Array) && paths.all? { |path| path.is_a?(String) || path.respond_to?(:to_path) }
+    raise Riffer::ArgumentError, "catalog_files must be an Array of file paths" unless valid
+
+    @catalog_files = paths.map(&:to_s).freeze
+    @catalog = nil
+  end
+
+  #--
+  #: () -> Riffer::Catalog
+  def catalog
+    @catalog ||= Riffer::Catalog.load(@catalog_files)
+  end
+
+  #--
+  #: () -> Riffer::Catalog
+  def reload_catalog
+    @catalog = Riffer::Catalog.load(@catalog_files)
+  end
+
   # When not +:none+, seeded messages passed to +Riffer::Agent#generate+ must
   # carry their own +id+.
   attr_reader :message_id_strategy #: Symbol # @dynamic message_id_strategy
@@ -73,6 +100,8 @@ class Riffer::Config
     @tracing = Tracing.new
     @files = Files.new
     @pricing = Pricing.new
+    no_files = [] #: Array[String]
+    @catalog_files = no_files.freeze
     @message_id_strategy = :none
   end
 end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -78,6 +78,20 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     end
   end
 
+  # Claude's fields, since application inference profile ARNs hide the model
+  # family; other families need a catalog entry.
+  #--
+  #: (Symbol) -> Hash[Symbol, untyped]
+  def default_reasoning_options(level)
+    fields =
+      if level == :off
+        { thinking: { type: "disabled" } }
+      else
+        { thinking: { type: "adaptive" }, output_config: { effort: level.to_s } }
+      end
+    { additional_model_request_fields: fields }
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)

data/lib/riffer/providers/anthropic.rb

@@ -56,6 +56,14 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     ::Anthropic::Client.new(**{ api_key: Riffer.config.anthropic.api_key }.compact)
   end
 
+  #--
+  #: (Symbol) -> Hash[Symbol, untyped]
+  def default_reasoning_options(level)
+    return { thinking: { type: "disabled" } } if level == :off
+
+    { thinking: { type: "adaptive" }, output_config: { effort: level.to_s } }
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)

data/lib/riffer/providers/base.rb

@@ -39,6 +39,7 @@ class Riffer::Providers::Base
     validate_normalized_messages!(messages)
     Riffer::Files::Resolver.new(provider: self).resolve!(messages)
     messages = merge_consecutive_messages(with_structured_output_prompt(messages, options[:structured_output]))
+    options = apply_reasoning(model, options)
     params = build_request_params(messages, model, request_options(options))
 
     in_chat_span(model, messages, options) do |span|
@@ -77,6 +78,7 @@ class Riffer::Providers::Base
     validate_normalized_messages!(messages)
     Riffer::Files::Resolver.new(provider: self).resolve!(messages)
     messages = merge_consecutive_messages(with_structured_output_prompt(messages, options[:structured_output]))
+    options = apply_reasoning(model, options)
     params = build_request_params(messages, model, request_options(options))
 
     # The enumerator body runs in its own fiber, where the fiber-local OTEL
@@ -188,18 +190,64 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: () -> Riffer::Config::Pricing::Rates?
+  #: () -> Riffer::Catalog::Rates?
   def pricing_rates
     model = @current_model
     return nil unless model
 
-    pricing = Riffer.config.pricing
-    return nil if pricing.empty?
-
-    key = Riffer::Providers::Repository.key_for(self.class)
+    key = catalog_key(model)
     return nil unless key
 
-    pricing.rates_for("#{key}/#{model}")
+    Riffer.config.catalog.rates_for(key) || Riffer.config.pricing.rates_for(key)
+  end
+
+  #--
+  #: (String) -> String?
+  def catalog_key(model)
+    provider_key = Riffer::Providers::Repository.key_for(self.class)
+    "#{provider_key}/#{model}" if provider_key
+  end
+
+  # A catalog fragment beats the provider default per level; the caller's
+  # options are merged over either, so +model_options+ always wins.
+  #--
+  #: (String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def apply_reasoning(model, options)
+    value = options[:riffer_reasoning_level]
+    return options if value.nil?
+
+    level = value.to_s.to_sym
+    levels = Riffer::Agent::Config::REASONING_LEVELS
+    unless levels.include?(level)
+      raise Riffer::ArgumentError, "riffer_reasoning_level must be one of #{levels.join(', ')}, got #{value.inspect}"
+    end
+
+    key = model && catalog_key(model)
+    fragment = (key && Riffer.config.catalog.reasoning_options(key, level)) || default_reasoning_options(level)
+    unless fragment
+      raise Riffer::ArgumentError,
+            "No reasoning mapping for #{key || model.inspect} at level #{level.inspect}. " \
+            "Add one in a catalog file (see docs/CATALOG.md)."
+    end
+
+    # A copy, since catalog fragments are frozen and providers may edit nested params.
+    deep_merge(Riffer::Helpers::DeepDup.call(fragment), options.merge(riffer_reasoning_level: level))
+  end
+
+  # Maps a level onto the provider's own reasoning params when the catalog has
+  # no entry; +nil+ means riffer raises before the request.
+  #--
+  #: (Symbol) -> Hash[Symbol, untyped]?
+  def default_reasoning_options(_level)
+    nil
+  end
+
+  #--
+  #: (Hash[Symbol, untyped], Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def deep_merge(base, override)
+    base.merge(override) do |_key, base_value, override_value|
+      base_value.is_a?(Hash) && override_value.is_a?(Hash) ? deep_merge(base_value, override_value) : override_value
+    end
   end
 
   #--
@@ -274,6 +322,9 @@ class Riffer::Providers::Base
       attributes[attribute] = value if value
     end
 
+    reasoning_level = options[:riffer_reasoning_level]
+    attributes["riffer.request.reasoning_level"] = reasoning_level.to_s if reasoning_level
+
     attributes.merge(tag_attributes(options[:tags] || {}))
   end
 
@@ -388,6 +439,7 @@ class Riffer::Providers::Base
   #--
   #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def request_options(options)
+    options = options.except(:riffer_reasoning_level)
     options[:structured_output]&.prompted? ? options.except(:structured_output) : options
   end
 

data/lib/riffer/providers/gemini.rb

@@ -54,6 +54,12 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     Riffer::Providers::Gemini::Client.new(**{ api_key: Riffer.config.gemini.api_key }.compact)
   end
 
+  #--
+  #: (Symbol) -> Hash[Symbol, untyped]
+  def default_reasoning_options(level)
+    { thinkingConfig: { thinkingLevel: level.to_s } }
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)

data/lib/riffer/providers/mock.rb

@@ -75,6 +75,13 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     }
   end
 
+  # Never raises, so test suites can set +reasoning+ without catalog entries.
+  #--
+  #: (Symbol) -> Hash[Symbol, untyped]
+  def default_reasoning_options(_level)
+    {}
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)

data/lib/riffer/providers/open_ai.rb

@@ -56,6 +56,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     }.compact)
   end
 
+  #--
+  #: (Symbol) -> Hash[Symbol, untyped]
+  def default_reasoning_options(level)
+    { reasoning: level == :off ? "none" : level.to_s }
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)

data/lib/riffer/providers/open_router.rb

@@ -72,6 +72,12 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     ::OpenAI::Client.new(api_key: api_key, base_url: BASE_URL)
   end
 
+  #--
+  #: (Symbol) -> Hash[Symbol, untyped]
+  def default_reasoning_options(level)
+    { reasoning: level == :off ? "none" : level.to_s }
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.52.1" #: String
+  VERSION = "0.53.0" #: String
 end

data/lib/riffer.rb

@@ -62,10 +62,12 @@ module Riffer
     @config ||= Config.new
   end
 
+  # Builds the catalog after the block, so a bad catalog file fails boot.
   #--
   #: () ?{ (Riffer::Config) -> void } -> void
   def configure(&)
     yield config if block_given?
+    config.reload_catalog
   end
 
   #--

data/sig/generated/riffer/agent/config.rbs

@@ -5,6 +5,8 @@ class Riffer::Agent::Config
 
   STRUCTURED_OUTPUT_STRATEGIES: Array[Symbol]
 
+  REASONING_LEVELS: Array[Symbol]
+
   @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
 
   attr_reader identifier: String?
@@ -21,6 +23,8 @@ class Riffer::Agent::Config
 
   attr_accessor max_steps: Numeric?
 
+  attr_reader reasoning: Symbol?
+
   attr_accessor tools_config: (Array[singleton(Riffer::Tool)] | Proc)?
 
   attr_reader mcp_configs: Array[Hash[Symbol, untyped]]
@@ -38,13 +42,14 @@ class Riffer::Agent::Config
   #     ?structured_output: Riffer::Params?,
   #     ?structured_output_strategy: Symbol,
   #     ?max_steps: Numeric?,
+  #     ?reasoning: (Symbol | String)?,
   #     ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
   #     ?mcp_configs: Array[Hash[Symbol, untyped]],
   #     ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
   #     ?skills_config: Riffer::Skills::Config?,
   #     ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
   #   ) -> void
-  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?structured_output_strategy: Symbol, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
+  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?structured_output_strategy: Symbol, ?max_steps: Numeric?, ?reasoning: (Symbol | String)?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
 
   # --
   # : (untyped) -> String?
@@ -58,6 +63,10 @@ class Riffer::Agent::Config
   # : (Symbol) -> Symbol
   def structured_output_strategy=: (Symbol) -> Symbol
 
+  # --
+  # : ((Symbol | String)?) -> Symbol?
+  def reasoning=: ((Symbol | String)?) -> Symbol?
+
   # --
   # : () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime: () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)

data/sig/generated/riffer/agent.rbs

@@ -39,6 +39,10 @@ class Riffer::Agent
   # : (*Numeric?) -> Numeric?
   def self.max_steps: (*Numeric?) -> Numeric?
 
+  # --
+  # : (?(Symbol | String)?) -> Symbol?
+  def self.reasoning: (?(Symbol | String)?) -> Symbol?
+
   # --
   # : (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
   def self.uses_tools: (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?