riffer 0.52.1 → 0.53.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdd49e9dd195fd8a90f82297b355f5a267fe79d15a909bb40219fcc5faedc1ea
-  data.tar.gz: c0aeeffd8b3aba99953c1efc2ac186a65d86611bd4c9e690cdd31c8834e8242d
+  metadata.gz: 70784c56c20102b8da3e1e147bc843db2287e2be910f1e10d26b8ee9a2f8e0f9
+  data.tar.gz: 6df766acde899e39867a06de11fca0d013671e4bda34d3759b4ae310a43d04de
 SHA512:
-  metadata.gz: fc7d4287a7a94b1891d95d2c048e8ad3d5cd1cac9e7cae3047887316ed52224aa8f72a0c01eaba5d0ba1ebe1b4d78b48de42cc4a00114d5a8119fefe405f0e58
-  data.tar.gz: db472038a3c65f8643e792c987a837e1955c0699d3a2fd6297612e7f3bc8a8374f56751541663e9662f6da2dea0381a219d43b32b96eef30d6716d9662fdb540
+  metadata.gz: 39af9afa9f695fe6dcc661915e1173ddf812db2ee425b83f77ee42d2080cea623b0f03f82c80ae606e7b4caf2f42bb3799a63ed0955ab7baa13b2c30861a2781
+  data.tar.gz: 1f79ef71cf1a838092444368f6986cd772803aeffe0de9acadc5cf8c23834e0e56c04e5049001eaeab3360d13a0eb3767a8118f429cacdbad7372879706ce332

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.52.1"
+  ".": "0.53.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.53.0](https://github.com/janeapp/riffer/compare/riffer/v0.52.1...riffer/v0.53.0) (2026-10-13)
+
+
+### Features
+
+* **catalog:** add a model catalog and a cross-provider reasoning setting ([#480](https://github.com/janeapp/riffer/issues/480)) ([7144f54](https://github.com/janeapp/riffer/commit/7144f54022257217f4e9ebee3263b5627cb96544))
+
 ## [0.52.1](https://github.com/janeapp/riffer/compare/riffer/v0.52.0...riffer/v0.52.1) (2026-10-09)
 
 

data/docs/AGENTS.md

@@ -139,6 +139,21 @@ class MyAgent < Riffer::Agent
 end
 ```
 
+### reasoning
+
+Sets how much the model thinks before it answers: `:off`, `:low`, `:medium`, `:high`, `:xhigh`, or `:max` (a String works too). Anything else raises `Riffer::ArgumentError`. Leave it unset to send nothing and keep the model's default.
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'anthropic/claude-sonnet-4-6'
+  reasoning :low
+end
+```
+
+Riffer turns the level into the provider's own params. It uses the model's [catalog](CATALOG.md#reasoning) entry when one defines the level, and otherwise the provider's default, which sends the level name as the provider's effort value (for example `output_config: { effort: "low" }` with adaptive thinking on Anthropic). Riffer doesn't check whether the model supports the level; a model that rejects it returns the provider's error.
+
+`model_options` are deep-merged over those params, so they override single fields rather than whole blocks. For example, `model_options max_tokens: 8000` keeps the catalog's thinking budget and replaces only its `max_tokens`.
+
 ### max_steps
 
 Sets the maximum number of LLM call steps in the tool-use loop. When the limit is reached, the loop interrupts with reason `:max_steps`. Defaults to `16`. Set to `nil` (`max_steps nil`) for unlimited steps:

data/docs/CATALOG.md

@@ -0,0 +1,205 @@
+# Model Catalog
+
+The model catalog holds per-model data that riffer can't derive from the model name: how a [`reasoning`](AGENTS.md#reasoning) level maps to request params, and what the model costs. It lives in JSON files you list in your configuration, so a new model or a price change is a data edit, not a riffer release.
+
+Riffer ships no catalog. Without one:
+
+- `reasoning` still works through each provider's default mapping (see [Provider defaults](#provider-defaults)).
+- Calls carry no cost (`token_usage.cost` is `nil`), unless the deprecated [`config.pricing`](CONFIGURATION.md#pricing-deprecated) prices the model.
+
+## Loading catalog files
+
+```ruby
+Riffer.configure do |config|
+  config.catalog_files = ["config/riffer/models.json"]
+end
+```
+
+- `catalog_files` takes an Array of paths (Strings or Pathnames). Files load in the order listed.
+- `Riffer.configure` builds the catalog at the end of the block, so a missing file or invalid data raises `Riffer::ArgumentError` at boot.
+- Calling `configure` again rebuilds the catalog from scratch.
+- Files load at boot only. There is no API to add entries at runtime. The built catalog is frozen.
+
+## File format
+
+```json
+{
+  "version": 1,
+  "models": {
+    "anthropic/claude-haiku-4-5-20251001": {
+      "aliases": ["anthropic/claude-haiku-4-5"],
+      "pricing": {
+        "input": 1.0,
+        "output": 5.0,
+        "cache_read": 0.1,
+        "cache_write": 1.25
+      },
+      "reasoning": {
+        "off": { "thinking": { "type": "disabled" } },
+        "low": {
+          "thinking": { "type": "enabled", "budget_tokens": 1024 },
+          "max_tokens": 5120
+        },
+        "high": {
+          "thinking": { "type": "enabled", "budget_tokens": 24576 },
+          "max_tokens": 28672
+        }
+      }
+    },
+    "gemini/gemini-2.5-flash": {
+      "reasoning": {
+        "off": { "thinkingConfig": { "thinkingBudget": 0 } },
+        "low": { "thinkingConfig": { "thinkingBudget": 1024 } }
+      }
+    },
+    "amazon_bedrock/us.amazon.nova-2-lite-v1:0": {
+      "reasoning": {
+        "low": {
+          "additional_model_request_fields": {
+            "reasoningConfig": {
+              "type": "enabled",
+              "maxReasoningEffort": "low"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+| Key       | Description                                                                                |
+| --------- | ------------------------------------------------------------------------------------------ |
+| `version` | Required. The file format version. Only `1` is supported.                                  |
+| `models`  | An object keyed by exact `provider/model` id: the same string you give an agent's `model`. |
+
+Each model entry can have any of these keys:
+
+| Key         | Description                                                                                                                                                       |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `aliases`   | Other `provider/model` ids that share this entry, pricing included. An alias may name a different provider, e.g. `"azure_openai/my-gpt-prod"` on an OpenAI entry. |
+| `pricing`   | Per-million-token rates. See [Pricing](#pricing).                                                                                                                 |
+| `reasoning` | An object keyed by level (`off`, `low`, `medium`, `high`, `xhigh`, `max`). Each value is a `model_options` fragment. See [Reasoning](#reasoning).                 |
+
+### Lookup
+
+A model id matches an entry by its exact key first, then by an alias. There are no patterns, families, or fallback entries.
+
+The provider part of the key is the provider's [repository](providers/CUSTOM_PROVIDERS.md#registering-your-provider) identifier, so a custom provider registered as `:my_provider` reads entries under `my_provider/...`.
+
+## Reasoning
+
+A reasoning fragment is written exactly as you would write it in `model_options`, using the provider's own param names. Bedrock fragments spell out `additional_model_request_fields` and `inference_config` themselves.
+
+When an agent sets `reasoning`, riffer picks the params for that level in this order:
+
+1. The catalog entry's fragment for the level (by exact key, then alias).
+2. The provider's default mapping, when the entry is missing or doesn't define the level.
+3. If the provider has no default either, riffer raises `Riffer::ArgumentError` before the request:
+   `No reasoning mapping for my_provider/my-model at level :low. Add one in a catalog file (see docs/CATALOG.md).`
+
+Riffer doesn't check whether a model supports a level. If the model rejects the params, you get the provider's error unchanged.
+
+### Provider defaults
+
+The defaults send the level name as the provider's effort value:
+
+| Provider             | `:off`                                                                | Other levels                                                                                                |
+| -------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| OpenAI, Azure OpenAI | `reasoning: "none"`                                                   | `reasoning: "<level>"`                                                                                      |
+| OpenRouter           | `reasoning: "none"`                                                   | `reasoning: "<level>"`                                                                                      |
+| Anthropic            | `thinking: { type: "disabled" }`                                      | `thinking: { type: "adaptive" }, output_config: { effort: "<level>" }`                                      |
+| Amazon Bedrock       | `additional_model_request_fields: { thinking: { type: "disabled" } }` | `additional_model_request_fields: { thinking: { type: "adaptive" }, output_config: { effort: "<level>" } }` |
+| Gemini               | `thinkingConfig: { thinkingLevel: "off" }`                            | `thinkingConfig: { thinkingLevel: "<level>" }`                                                              |
+| Mock                 | nothing                                                               | nothing                                                                                                     |
+
+Add a catalog entry for models that need different params, for example:
+
+- Claude 4.5 and earlier, which take a `budget_tokens` thinking budget instead of adaptive thinking.
+- Gemini 2.5, which takes `thinkingBudget`.
+- Non-Claude models on Amazon Bedrock (Nova, OpenAI), which use their own fields.
+
+A [custom provider](providers/CUSTOM_PROVIDERS.md#reasoning-level) can supply its own default.
+
+### Merging with model_options
+
+The agent's `model_options` always win. Riffer deep-merges them over the fragment: nested objects merge key by key, and any other value (including arrays) replaces the fragment's. So you can override one field without repeating the rest:
+
+```ruby
+class SummaryAgent < Riffer::Agent
+  model "anthropic/claude-haiku-4-5-20251001"
+  reasoning :low
+  model_options max_tokens: 8000 # keeps the catalog's thinking budget, replaces its max_tokens
+end
+```
+
+Riffer doesn't check the merged result. If a partial override makes the request invalid, the provider rejects it.
+
+## Pricing
+
+```json
+{
+  "pricing": {
+    "input": 3.0,
+    "output": 15.0,
+    "cache_read": 0.3,
+    "cache_write": 3.75
+  }
+}
+```
+
+| Key           | Description                                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `input`       | Required. Price per **million** input tokens. Applies to the uncached portion of `input_tokens`. |
+| `output`      | Required. Price per **million** output tokens.                                                   |
+| `cache_read`  | Price per million cache-read tokens. When omitted, cache reads bill at the `input` rate.         |
+| `cache_write` | Price per million cache-write tokens. When omitted, cache writes bill at the `input` rate.       |
+
+Because the cache buckets are subsets of `input_tokens`, the cost formula subtracts them before applying the input rate:
+
+```text
+cost = (input − cache_read − cache_write) × input_rate
+     + cache_read  × cache_read_rate
+     + cache_write × cache_write_rate
+     + output      × output_rate
+```
+
+(all rates ÷ 1,000,000; an unset cache rate falls back to `input_rate`.) Cost is for observability, not billing: it's a `Float`, and sub-cent rounding can accumulate over a long run. See [Messages → Token Usage Semantics](MESSAGES.md#token-usage-semantics) for how cost surfaces and aggregates.
+
+A model with no catalog pricing carries no cost. The deprecated [`config.pricing`](CONFIGURATION.md#pricing-deprecated) is still read as a fallback; catalog pricing wins when both price a model.
+
+## Layering files
+
+Later files override earlier ones, so you can keep shared data in one file and local overrides in another:
+
+- For an entry with the same key, a later file replaces whole sections (`pricing`, `reasoning`) and leaves the others alone.
+- `aliases` arrays are combined, so a later file can add aliases without repeating earlier ones.
+- If a later file lists an alias an earlier file gave to a different entry, the later file wins.
+
+```json
+{
+  "version": 1,
+  "models": {
+    "anthropic/claude-haiku-4-5-20251001": {
+      "pricing": { "input": 0.8, "output": 4.0 }
+    },
+    "openai/gpt-5.1": {
+      "aliases": ["azure_openai/my-gpt-prod"]
+    }
+  }
+}
+```
+
+Listed after the first example, this file replaces Haiku's pricing but keeps its reasoning, and routes an Azure deployment to the `openai/gpt-5.1` entry.
+
+## Validation
+
+Loading raises `Riffer::ArgumentError`, naming the file and the model key, when:
+
+- The file is missing or isn't valid JSON, or `version` is missing or unsupported.
+- The file has keys other than `version` and `models`, or an entry has keys other than `aliases`, `pricing`, and `reasoning`.
+- A model key or alias isn't in `provider/model` form, or `aliases` isn't an array of strings.
+- `pricing` is missing `input` or `output`, has unknown keys, or has a rate that isn't a non-negative number.
+- A reasoning level isn't one of `off`, `low`, `medium`, `high`, `xhigh`, `max`, or its value isn't an object.
+- Two entries in the same file list the same alias.
+- After all files are layered, an alias is also a model key.

data/docs/CONFIGURATION.md

@@ -224,39 +224,38 @@ Every download in step 3 or 4 is gated by `allow_downloads`; with it `false` (th
 
 A file that fails resolution raises a `Riffer::FileError` subclass — `Riffer::FileUnsupportedError`, `Riffer::FileDownloadsDisabledError`, `Riffer::TooManyFilesError`, `Riffer::FileChecksumMismatchError`, `Riffer::FileTooLargeError`, `Riffer::FileDownloadError`, or `Riffer::FileEncodingError` — so callers can `rescue Riffer::FileError` for any attachment problem, or a specific subclass to handle one case.
 
-### Pricing
+### Model Catalog
 
-Configure per-model token prices and riffer computes the cost of each LLM call onto its [`TokenUsage`](MESSAGES.md#token-usage-semantics). Riffer ships **no** price table — so an unconfigured model simply carries no cost (`token_usage.cost` is `nil`).
+List JSON catalog files that hold per-model reasoning mappings and pricing. Riffer ships no catalog, so without one, `reasoning` uses each provider's default mapping, and calls carry no cost unless the deprecated [`config.pricing`](#pricing-deprecated) prices the model.
 
 ```ruby
 Riffer.configure do |config|
-  # Rates are per million tokens, keyed by the same "provider/model" id you give the agent.
-  config.pricing.set("anthropic/claude-sonnet-4-6", input: 3.0, output: 15.0, cache_read: 0.30, cache_write: 3.75)
-  config.pricing.set("openai/gpt-4", input: 30.0, output: 60.0)
+  config.catalog_files = ["config/riffer/models.json"]
+end
+```
+
+| Option          | Description                                                                                                                         |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `catalog_files` | Array of paths (Strings or Pathnames), loaded in order; later files override earlier ones. Built at the end of `Riffer.configure`. |
+
+See [Model Catalog](CATALOG.md) for the file format, lookup, layering, and validation.
 
-  # Pass an array to share one set of rates across a model family:
-  config.pricing.set(["openai/gpt-4", "openai/gpt-4-0613"], input: 30.0, output: 60.0)
+### Pricing (deprecated)
+
+`config.pricing` is deprecated and will be removed in a future release. Move rates into a [catalog file](CATALOG.md#pricing); the first `set` call prints a deprecation warning. Riffer still reads these rates as a fallback, and catalog pricing wins when both price a model.
+
+```ruby
+# before
+Riffer.configure do |config|
+  config.pricing.set("anthropic/claude-sonnet-4-6", input: 3.0, output: 15.0)
 end
 ```
 
-| Argument       | Description                                                                                                                                                                        |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `models`       | A `provider/model` id (e.g. `"openai/gpt-4"`) — the same string you pass to `model` — or an array of ids that share one set of rates. No alias matching; raises on a malformed id. |
-| `input:`       | Price per **million** input tokens. Required. Applies to the uncached portion of `input_tokens`.                                                                                   |
-| `output:`      | Price per **million** output tokens. Required.                                                                                                                                     |
-| `cache_read:`  | Price per million cache-read tokens. Optional — when omitted, cache reads bill at the `input:` rate.                                                                               |
-| `cache_write:` | Price per million cache-write tokens. Optional — when omitted, cache writes bill at the `input:` rate.                                                                             |
-
-Because the cache buckets are subsets of `input_tokens`, the cost formula subtracts them before applying the input rate:
-
-```text
-cost = (input − cache_read − cache_write) × input_rate
-     + cache_read  × cache_read_rate
-     + cache_write × cache_write_rate
-     + output      × output_rate
+```json
+{ "version": 1, "models": { "anthropic/claude-sonnet-4-6": { "pricing": { "input": 3.0, "output": 15.0 } } } }
 ```
 
-(all rates ÷ 1,000,000; an unset cache rate falls back to `input_rate`.) Cost is for observability, not billing — it's a `Float`, and sub-cent rounding can accumulate over a long run. See [Messages → Token Usage Semantics](MESSAGES.md#token-usage-semantics) for how cost surfaces and aggregates.
+`set` takes a `provider/model` id or an array of ids, plus `input:`, `output:`, and optional `cache_read:` and `cache_write:` rates per million tokens. The rates and cost formula are the same as [catalog pricing](CATALOG.md#pricing).
 
 ### Message ID Strategy
 
@@ -297,6 +296,19 @@ class MyAgent < Riffer::Agent
 end
 ```
 
+### reasoning
+
+Set how much the model thinks before it answers, with one setting that works on every provider:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'anthropic/claude-sonnet-4-6'
+  reasoning :low # :off, :low, :medium, :high, :xhigh, or :max
+end
+```
+
+Riffer maps the level to the provider's own params, from a [catalog](CATALOG.md#reasoning) entry or the provider's default. `model_options` are deep-merged over those params and win. See [Agents — reasoning](AGENTS.md#reasoning).
+
 ## Common Model Options
 
 ### OpenAI

data/docs/MESSAGES.md

@@ -91,7 +91,7 @@ tool_call.to_h             # => {call_id: "call_123", name: "weather_tool", argu
 
 The cache buckets are subsets of `input_tokens`, never additions to it — summing `input_tokens + cache_read_tokens` double-counts. `total_tokens` (input + output) matches the totals providers report on their dashboards.
 
-- `cost` — the computed cost of the call, set when pricing is configured for the model in use (see [Configuration → Pricing](CONFIGURATION.md#pricing)); `nil` when the model is unpriced. It's for observability, not billing. Run-level usage sums per-call costs through `TokenUsage#+`, so `response.token_usage.cost` is the total spend across the run — but the sum is `nil` if any call in the run used an unpriced model, rather than silently under-reporting.
+- `cost` — the computed cost of the call, set when a [catalog](CATALOG.md#pricing) or the deprecated [`config.pricing`](CONFIGURATION.md#pricing-deprecated) prices the model in use; `nil` when the model is unpriced. It's for observability, not billing. Run-level usage sums per-call costs through `TokenUsage#+`, so `response.token_usage.cost` is the total spend across the run — but the sum is `nil` if any call in the run used an unpriced model, rather than silently under-reporting.
 
 #### Finish Reasons
 

data/docs/SERIALIZATION.md

@@ -46,6 +46,7 @@ The session is used **as-is**: the rebuilt agent does not prepend anything to it
   max_steps:         8,                        # integer; -1 = unlimited (see below)
   structured_output: { type: "object", … },   # JSON Schema, or null
   structured_output_strategy: :native,        # :native or :prompted ("native"/"prompted" over JSON)
+  reasoning:         :low,                     # reasoning level, or null
   tools: [ { name:, description:, parameters_schema:, timeout: }, … ]
 }
 ```

data/docs/TRACING.md

@@ -142,6 +142,7 @@ Usage on this span is the run total, aggregated across every step. See [Token us
 | `gen_ai.request.presence_penalty`          | float    | When the caller set it                                                        |
 | `gen_ai.request.seed`                      | int      | When the caller set it                                                        |
 | `gen_ai.request.stop_sequences`            | string[] | When the caller set it                                                        |
+| `riffer.request.reasoning_level`           | string   | When the agent sets [`reasoning`](AGENTS.md#reasoning)                        |
 | `gen_ai.usage.input_tokens`                | int      | When the provider reported usage                                              |
 | `gen_ai.usage.output_tokens`               | int      | When the provider reported usage                                              |
 | `gen_ai.usage.cache_read.input_tokens`     | int      | When the provider reported cache reads                                        |
@@ -252,7 +253,7 @@ Riffer normalizes this across providers, so the number may differ from a provide
 
 ### Cost
 
-`riffer.cost` is the modeled cost of one call (on a `chat` span) or a whole run (on the `invoke_agent` span). It lives in Riffer's own namespace because the GenAI semantic conventions define no cost attribute by design — Riffer never squats `gen_ai.*` for it. The attribute appears only when you have configured pricing for the model in use: Riffer ships no price table and never guesses, so an unpriced model simply carries no `riffer.cost`. See [Configuration — Pricing](CONFIGURATION.md#pricing) for the rates.
+`riffer.cost` is the modeled cost of one call (on a `chat` span) or a whole run (on the `invoke_agent` span). It lives in Riffer's own namespace because the GenAI semantic conventions define no cost attribute by design — Riffer never squats `gen_ai.*` for it. The attribute appears only when a [catalog](CATALOG.md#pricing) or the deprecated [`config.pricing`](CONFIGURATION.md#pricing-deprecated) prices the model in use: Riffer ships no price table and never guesses, so an unpriced model simply carries no `riffer.cost`.
 
 The value is **unitless on the wire** — Riffer attaches no currency. It is the sum of the per-token rates you configured, in whatever currency you expressed them, so a `riffer.cost` of `0.0123` means 0.0123 of that unit. The raw float is emitted unrounded; round for display in your backend, not before.
 

data/docs/providers/AMAZON_BEDROCK.md

@@ -189,6 +189,8 @@ end
 
 The reasoning is kept on the assistant message as [reasoning parts](../MESSAGES.md#reasoning), whether you call `generate` or `stream`. Read it with `response.reasoning`, or as plain text with `reasoning_text` on the message. Bedrock sometimes redacts part of Claude's reasoning. Those parts are stored and sent back like any other, but they have no readable text, so `reasoning_text` leaves them out.
 
+The agent-level [`reasoning`](../AGENTS.md#reasoning) setting defaults to Claude's fields inside `additional_model_request_fields`: adaptive thinking at the level's effort, and `thinking: {type: "disabled"}` for `:off`. Other model families (Nova, OpenAI) and Claude 4.5 and earlier need a [catalog](../CATALOG.md#reasoning) entry with their own fields.
+
 ### Reasoning Replay
 
 Riffer sends the reasoning back to Bedrock on every later turn. How much of it Claude uses depends on the model; some only use the reasoning from the current tool-calling turn. For tool calls, sending it back is required: when thinking is enabled, Claude needs its earlier reasoning back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.

data/docs/providers/ANTHROPIC.md

@@ -170,6 +170,8 @@ class ReasoningAgent < Riffer::Agent
 end
 ```
 
+The agent-level [`reasoning`](../AGENTS.md#reasoning) setting defaults to adaptive thinking at the level's effort (`thinking: {type: "adaptive"}, output_config: {effort: "low"}`), and `:off` sends `thinking: {type: "disabled"}`. Claude 4.5 and earlier need a `budget_tokens` mapping in a [catalog](../CATALOG.md#reasoning) entry instead.
+
 When streaming with extended thinking enabled, you'll receive `ReasoningDelta` events containing the model's thought process, followed by a `ReasoningDone` event when thinking completes:
 
 ```ruby

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

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.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)