riffer 0.52.1 → 0.54.0

data/docs/providers/AZURE_OPENAI.md

@@ -87,6 +87,8 @@ Enables extended thinking (for supported models):
 model_options reasoning: 'medium'  # 'low', 'medium', or 'high'
 ```
 
+The agent-level [`reasoning`](../AGENTS.md#reasoning) setting maps to this option the same way as on the [OpenAI provider](OPENAI.md#reasoning).
+
 Reasoning is captured and replayed on later turns exactly as with the [OpenAI provider](OPENAI.md#reasoning-replay), except that parts are tagged `format: "azure-openai-v1"`. Azure only accepts reasoning produced by the same resource, so parts from the OpenAI provider are never sent to Azure, and Azure's are never sent to OpenAI.
 
 ### structured_output

data/docs/providers/CUSTOM_PROVIDERS.md

@@ -157,7 +157,7 @@ Register your provider under an identifier.
 Riffer::Providers::Repository.register(:my_provider) { Riffer::Providers::MyProvider }
 ```
 
-The block resolves the provider class lazily, so it need not be loaded at registration time. Registration is idempotent — re-registering the same identifier replaces the previous factory — and a custom registration takes precedence over a built-in sharing the identifier, which lets you route an existing prefix (e.g. `openai`) through your own backend. Both `find` and `key_for` (used for pricing and observability keys) honor the registration. Remove one with `Riffer::Providers::Repository.unregister(:my_provider)`.
+The block resolves the provider class lazily, so it need not be loaded at registration time. Registration is idempotent — re-registering the same identifier replaces the previous factory — and a custom registration takes precedence over a built-in sharing the identifier, which lets you route an existing prefix (e.g. `openai`) through your own backend. Both `find` and `key_for` (used for [catalog](../CATALOG.md) keys) honor the registration. Remove one with `Riffer::Providers::Repository.unregister(:my_provider)`.
 
 Register during application boot — from a Rails initializer or equivalent — before you start handling requests. The registry is not synchronized for concurrent mutation, so treat registration as a one-time setup step rather than something you do from a live request path.
 
@@ -308,6 +308,20 @@ yielder << Riffer::StreamEvents::ReasoningDone.new(part)
 
 If your adapter surfaces reasoning text but cannot yet replay it, call `yield_reasoning_done(yielder, text)` instead. It wraps the text in a `:text` part with no `format`, which persists for display and is skipped on replay.
 
+## Reasoning Level
+
+When an agent sets [`reasoning`](../AGENTS.md#reasoning), riffer resolves the level to `model_options` params before calling `build_request_params`, so your provider receives ordinary options and never sees the level itself. It uses the model's [catalog](../CATALOG.md#reasoning) entry under your registration key first, then your provider's default. Override the private `default_reasoning_options` to supply one:
+
+```ruby
+private
+
+def default_reasoning_options(level)
+  { reasoning_effort: level.to_s }
+end
+```
+
+The base class returns `nil`, which makes riffer raise `Riffer::ArgumentError` for any level the catalog doesn't map.
+
 ## Tags
 
 Every agent and judge call passes a `:tags` option: a flat `String => String` hash of the caller's [per-call tags](../AGENTS.md#per-call-tags) plus the [default tags](../AGENTS.md#default-tags). `kind` (`"agent"` or `"judge"`) and `agent` (the agent or evaluator identifier) tell you who the call is on behalf of:

data/docs/providers/GEMINI.md

@@ -80,6 +80,16 @@ Nucleus sampling:
 model_options topP: 0.9
 ```
 
+### thinkingConfig
+
+Controls thinking, passed through as Gemini expects:
+
+```ruby
+model_options thinkingConfig: {thinkingLevel: "low"}
+```
+
+The agent-level [`reasoning`](../AGENTS.md#reasoning) setting writes `thinkingConfig: {thinkingLevel: "<level>"}` by default, including `"off"` for `:off`, which Gemini rejects. Gemini 2.5 models take `thinkingBudget` instead; map them in a [catalog](../CATALOG.md#reasoning) entry.
+
 ## Usage
 
 ### Basic Generation
@@ -162,3 +172,4 @@ A `FilePart.from_url` source works too — riffer downloads and base64-encodes i
 
 - **No web search** - Gemini's standard API does not include a web search tool
 - **Tool call IDs** - Gemini does not return unique call IDs for tool invocations; IDs are generated client-side
+- **String enums only** - Gemini rejects non-string `enum` values, including on `Array, of:` items

data/docs/providers/MOCK_PROVIDER.md

@@ -64,6 +64,8 @@ agent.session.messages.last.reasoning_text  # => "The user wants the answer."
 
 When streaming, each part is emitted as a `ReasoningDelta` (only when it carries `text`) followed by a `ReasoningDone` carrying the part, ahead of the text events.
 
+An agent's [`reasoning`](../AGENTS.md#reasoning) level needs no catalog entry on the mock provider: it maps every level to no params, so `calls` show only your `model_options` unless a [catalog](../CATALOG.md) entry under `mock/...` maps the level.
+
 ## Queueing Multiple Responses
 
 Responses are consumed in order:

data/docs/providers/OPENAI.md

@@ -82,6 +82,8 @@ model_options reasoning: 'medium'  # 'low', 'medium', or 'high'
 
 When reasoning is enabled, you'll receive `ReasoningDelta` and `ReasoningDone` events during streaming.
 
+The agent-level [`reasoning`](../AGENTS.md#reasoning) setting writes this same option by default: `reasoning :low` sends `reasoning: 'low'`, and `:off` sends `'none'`. A [catalog](../CATALOG.md#reasoning) entry can map a level differently.
+
 #### Reasoning Replay
 
 Each `reasoning` item in a Responses API output becomes [reasoning parts](../MESSAGES.md#reasoning) on the assistant message, on both `generate_text` and `stream_text`, all tagged `format: "openai-v1"` and carrying the item's `id`:

data/docs/providers/OPENROUTER.md

@@ -80,6 +80,8 @@ model_options reasoning: {effort: 'medium', max_tokens: 5000}
 
 Streaming yields `Riffer::StreamEvents::ReasoningDelta` and `ReasoningDone` events when the model returns reasoning content.
 
+The agent-level [`reasoning`](../AGENTS.md#reasoning) setting writes this same option by default: `reasoning :low` sends `reasoning: 'low'`, and `:off` sends `'none'`. A [catalog](../CATALOG.md#reasoning) entry can map a level differently.
+
 ### provider (routing preferences)
 
 Pin which upstream provider OpenRouter should use, set allow/deny lists, or prefer a sort order:

data/docs-site/manifest.yml

@@ -45,6 +45,9 @@ groups:
       - source: CONFIGURATION.md
         slug: configuration
         description: Framework configuration
+      - source: CATALOG.md
+        slug: catalog
+        description: Reasoning mappings and pricing per model
       - source: EVALS.md
         slug: evals
         description: Evaluating agent quality

data/lib/riffer/agent/config.rb

@@ -5,6 +5,8 @@ class Riffer::Agent::Config
   DEFAULT_MAX_STEPS = 16 #: Integer
   STRUCTURED_OUTPUT_STRATEGIES = %i[native prompted].freeze #: Array[Symbol]
 
+  REASONING_LEVELS = %i[off low medium high xhigh max].freeze #: Array[Symbol]
+
   # @rbs @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
 
   attr_reader :identifier #: String? # @dynamic identifier
@@ -14,6 +16,7 @@ class Riffer::Agent::Config
   attr_reader :structured_output #: Riffer::Params? # @dynamic structured_output
   attr_reader :structured_output_strategy #: Symbol # @dynamic structured_output_strategy
   attr_accessor :max_steps #: Numeric? # @dynamic max_steps, max_steps=
+  attr_reader :reasoning #: Symbol? # @dynamic reasoning
   attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic tools_config, tools_config=
   attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]] # @dynamic mcp_configs
   attr_accessor :skills_config #: Riffer::Skills::Config? # @dynamic skills_config, skills_config=
@@ -28,6 +31,7 @@ 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)?,
@@ -42,6 +46,7 @@ class Riffer::Agent::Config
     structured_output: nil,
     structured_output_strategy: :native,
     max_steps: DEFAULT_MAX_STEPS,
+    reasoning: nil,
     tools_config: nil,
     mcp_configs: [],
     tool_runtime: nil,
@@ -59,6 +64,7 @@ class Riffer::Agent::Config
     self.instructions = instructions
     self.structured_output = structured_output
     self.structured_output_strategy = structured_output_strategy
+    self.reasoning = reasoning
     self.tool_runtime = tool_runtime if tool_runtime
   end
 
@@ -89,6 +95,17 @@ class Riffer::Agent::Config
     @structured_output_strategy = value
   end
 
+  #--
+  #: ((Symbol | String)?) -> Symbol?
+  def reasoning=(value)
+    level = value&.to_s&.to_sym
+    unless level.nil? || REASONING_LEVELS.include?(level)
+      raise Riffer::ArgumentError, "reasoning must be one of #{REASONING_LEVELS.join(', ')}, got #{value.inspect}"
+    end
+
+    @reasoning = level
+  end
+
   #--
   #: () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime

data/lib/riffer/agent/run.rb

@@ -354,6 +354,8 @@ module Riffer::Agent::Run
   def merged_model_options(agent, tags = {})
     opts = agent.config.model_options.dup
     opts[:structured_output] = agent.structured_output if agent.structured_output
+    reasoning = agent.config.reasoning
+    opts[:riffer_reasoning_level] = reasoning if reasoning
     # Providers extract :tags for native request metadata; it never reaches an
     # SDK call verbatim.
     opts[:tags] = tags unless tags.empty?

data/lib/riffer/agent/serializer.rb

@@ -28,6 +28,7 @@ module Riffer::Agent::Serializer
       max_steps: encode_max_steps(config.max_steps),
       structured_output: config.structured_output&.to_json_schema(strict: false),
       structured_output_strategy: config.structured_output_strategy,
+      reasoning: config.reasoning,
       tools: agent.tools.map { |tool_class| tool_descriptor(tool_class) },
     }
   end
@@ -79,6 +80,7 @@ module Riffer::Agent::Serializer
       structured_output: decode_structured_output(hash[:structured_output]),
       structured_output_strategy: (hash[:structured_output_strategy] || :native).to_sym,
       max_steps: decode_max_steps(hash),
+      reasoning: hash[:reasoning],
       tools_config: tools,
     } #: Hash[Symbol, untyped]
     # Config#tool_runtime= rejects nil.

data/lib/riffer/agent/structured_output.rb

@@ -30,9 +30,14 @@ class Riffer::Agent::StructuredOutput
   #--
   #: () -> String
   def prompt_instructions
-    "When you give your final answer, respond with only a JSON object that conforms to " \
-      "the following JSON Schema, with no other text before or after it:\n\n" \
-      "#{JSON.generate(json_schema)}"
+    schema = json_schema
+    [
+      "When you give your final answer, respond with only a JSON object that conforms to " \
+      "the following JSON Schema, with no other text before or after it:",
+      JSON.generate(schema),
+      "Example of the shape (placeholder values):\n#{JSON.generate(placeholder(schema))}",
+      "Only call tools when the request needs them. If you can answer directly, reply with the JSON object right away.",
+    ].join("\n\n")
   end
 
   #--
@@ -46,4 +51,19 @@ class Riffer::Agent::StructuredOutput
   rescue Riffer::ValidationError => e
     Result.new(error: "Validation error: #{e.message}")
   end
+
+  private
+
+  #--
+  #: (Hash[Symbol, untyped]) -> untyped
+  def placeholder(schema)
+    return schema[:enum].join(" | ") if schema[:enum]
+    return placeholder(schema[:anyOf].first) if schema[:anyOf]
+
+    case schema[:type]
+    when "object" then (schema[:properties] || {}).transform_values { |property| placeholder(property) }
+    when "array" then schema[:items] ? [placeholder(schema[:items])] : []
+    else "<#{schema[:type]}>"
+    end
+  end
 end

data/lib/riffer/agent.rb

@@ -73,6 +73,13 @@ class Riffer::Agent
     config.max_steps = value.first
   end
 
+  #--
+  #: (?(Symbol | String)?) -> Symbol?
+  def self.reasoning(value = nil)
+    config.reasoning = value if value
+    config.reasoning
+  end
+
   #--
   #: (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
   def self.uses_tools(value = nil)

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/params/any_of.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Riffer::Params::AnyOf
+  attr_reader :variants #: Array[Riffer::Params] # @dynamic variants
+
+  #--
+  #: () -> void
+  def initialize
+    @variants = []
+  end
+
+  #--
+  #: () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def variant(&block)
+    raise Riffer::ArgumentError, "variant requires a block defining its properties" unless block
+
+    params = Riffer::Params.new
+    params.instance_eval(&block)
+    @variants << params
+  end
+end