riffer 0.52.1 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdd49e9dd195fd8a90f82297b355f5a267fe79d15a909bb40219fcc5faedc1ea
-  data.tar.gz: c0aeeffd8b3aba99953c1efc2ac186a65d86611bd4c9e690cdd31c8834e8242d
+  metadata.gz: da8c08b227ba3ddddaa025377b70f1dfb9acaa3c86b52ff9866446e8e908443c
+  data.tar.gz: 598cddab932d5f4e3c775847eafaba44d7d0fe21741539927fa1cad15cb1767e
 SHA512:
-  metadata.gz: fc7d4287a7a94b1891d95d2c048e8ad3d5cd1cac9e7cae3047887316ed52224aa8f72a0c01eaba5d0ba1ebe1b4d78b48de42cc4a00114d5a8119fefe405f0e58
-  data.tar.gz: db472038a3c65f8643e792c987a837e1955c0699d3a2fd6297612e7f3bc8a8374f56751541663e9662f6da2dea0381a219d43b32b96eef30d6716d9662fdb540
+  metadata.gz: d01ca1aa3fa2f183c93a7c783eb5d23040f8e76d403114abe4f53f2cb4a299b69046a0397c405380013467d0c035e9cb1b7e1fcc72b45e945a7a6c786159b274
+  data.tar.gz: 3f568d27f9b5cbd12d23be97acbe049d8e9dd70f817bc6375d273f2cae62d60cbc7ebf40d7588d516739107734a12f3b450863a13f327ed1e2d1d46b7f60ca1d

data/.claude/rules/rbs-inline.md

@@ -68,13 +68,13 @@ end
 
 ### Where stubs and stdlib deps live
 
-Dependency signatures come from [`rbs collection`](https://github.com/ruby/gem_rbs_collection): `rbs_collection.yaml` pins the upstream repo to a commit SHA, the gem set is derived from `Gemfile.lock`, and `rbs_collection.lock.yaml` is committed (the installed `.gem_rbs_collection/` is gitignored). Steep auto-detects the config, so the `Steepfile` declares no `library` lines. `yaml` is the one hand-listed entry under `gems:` — it's stdlib, so it never appears in `Gemfile.lock`.
+Dependency signatures come from [`rbs collection`](https://github.com/ruby/gem_rbs_collection): `rbs_collection.yaml` pins the upstream repo to a commit SHA, the gem set is derived from `Gemfile.lock`, and `rbs_collection.lock.yaml` is committed (the installed `.gem_rbs_collection/` is gitignored). Steep auto-detects the config, so the `Steepfile` declares no `library` lines. Stdlib libraries that no gem in `Gemfile.lock` pulls in are hand-listed under `gems:` (`yaml`, `cgi`, `date`, `ipaddr`).
 
 `bin/typecheck` runs `rbs collection update` before `steep check`, keeping the lock in sync with `Gemfile.lock`; CI fails on lock drift. So after a Dependabot gem bump, run `bin/typecheck` and commit the refreshed lock. To pull newer upstream stubs, bump `revision` in `rbs_collection.yaml` and run `bin/typecheck` — pinning is what makes `update` deterministic.
 
 - `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level — full stubs for the gems upstream has nothing for (`mcp.rbs`, `zeitwerk.rbs`, `opentelemetry.rbs`, `rspec.rbs`, `aws-sdk-core/*`) plus arity patches for the provider SDKs (`openai.rbs`, `anthropic.rbs`); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` narrows the private `client` method to the SDK-typed client). A stub must be **deleted** once the collection covers that gem, or RBS raises `DuplicatedMethodDefinitionError`.
 - `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Annotation Conventions"). SDK-typed signatures can't ship, so they go in `_private/riffer/providers/` (the narrowed `client`).
-- `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
+- `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`, `digest`, `ipaddr`) so `rbs -r riffer` resolves them.
 
 ## Workflow
 

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.54.0](https://github.com/janeapp/riffer/compare/riffer/v0.53.0...riffer/v0.54.0) (2026-10-20)
+
+
+### Features
+
+* **params:** add `format:` for string formats ([#497](https://github.com/janeapp/riffer/issues/497)) ([3c2dec8](https://github.com/janeapp/riffer/commit/3c2dec8e70b28de2d7b9d655e8d17ce85dde6812))
+* **params:** add `Riffer::Params::AnyOf` ([#491](https://github.com/janeapp/riffer/issues/491)) ([65493ca](https://github.com/janeapp/riffer/commit/65493caa8073cf86983ec27dc6fb84ede068b6b9))
+* **params:** add arrays of arrays with nested `of:` ([#498](https://github.com/janeapp/riffer/issues/498)) ([2b3449c](https://github.com/janeapp/riffer/commit/2b3449c61474f5cc79643903c08668a8fd9db8b6))
+* **structured_output:** append prompted schema to user messages ([#492](https://github.com/janeapp/riffer/issues/492)) ([332db21](https://github.com/janeapp/riffer/commit/332db216d2e7716904d5ff4a9c1d9d42e128ac83))
+
+
+### Bug Fixes
+
+* **params:** apply enum to each item of an Array of: param ([#493](https://github.com/janeapp/riffer/issues/493)) ([09da9b0](https://github.com/janeapp/riffer/commit/09da9b0ccb0e63b2ed3202a28546371b17118e8c))
+
+## [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/Steepfile

@@ -2,6 +2,25 @@
 
 D = Steep::Diagnostic
 
+# RBS 4.2.0 re-validates every declaration of a module each time its type
+# params are read, which is quadratic in how often a module is reopened. The
+# openai and anthropic gems reopen their namespace ~1,600 times each, so
+# loading signatures takes over a minute per Steep worker. Fixed upstream in
+# ruby/rbs a5458a83; delete this once the bundle has an RBS release newer
+# than 4.2.
+if RBS::Environment::ModuleEntry.instance_method(:validate_type_params).owner == RBS::Environment::ModuleEntry
+  validate_once = Module.new do
+    def validate_type_params
+      return if @validated_decl_count == context_decls.size
+
+      super
+      @validated_decl_count = context_decls.size
+    end
+  end
+  RBS::Environment::ModuleEntry.prepend(validate_once)
+  RBS::Environment::ClassEntry.prepend(validate_once)
+end
+
 target :lib do
   signature "sig/generated"
   signature "sig/manual"

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:
@@ -197,12 +212,12 @@ class SentimentAgent < Riffer::Agent
 end
 ```
 
-With `strategy: :prompted`, the provider never receives its native structured-output field. Instead, an instruction carrying the JSON Schema is appended to the system instructions on every request of the run (it is not stored in `session.messages`), and the reply is parsed and validated exactly as above: `response.content` is the reply's JSON text, `response.structured_output` holds the validated object, and a reply that fails parsing or validation ends with `:invalid_structured_output`. Because nothing forces the model to comply, expect more `:invalid_structured_output` outcomes than with the native strategy.
+With `strategy: :prompted`, the provider never receives its native structured-output field. Instead, an instruction is appended to the end of every user message on every request of the run, after consecutive user messages are merged (it is not stored in `session.messages`, and the system instructions are left untouched). The instruction carries the JSON Schema, an example of the expected shape with placeholder values (`"<string>"`, enum values as `"a | b"`, an `AnyOf` field as its first variant), and a nudge to reply with the JSON right away unless the request needs a tool. The reply is parsed and validated exactly as above: `response.content` is the reply's JSON text, `response.structured_output` holds the validated object, and a reply that fails parsing or validation ends with `:invalid_structured_output`. Because nothing forces the model to comply, expect more `:invalid_structured_output` outcomes than with the native strategy.
 
 | Strategy            | Behavior                                                        |
 | ------------------- | --------------------------------------------------------------- |
 | `:native` (default) | Schema sent through the provider's structured-output field      |
-| `:prompted`         | Schema sent in the system prompt; experimental, may change      |
+| `:prompted`         | Schema appended to each user message; experimental, may change  |
 
 Riffer does not pick a strategy per model — the choice is always yours. The strategy is copied to subclasses and survives [serialization](SERIALIZATION.md). An unknown value raises `Riffer::ArgumentError`. `strategy:` can also be passed with a `Riffer::Params` instance: `structured_output params, strategy: :prompted`.
 
@@ -234,7 +249,46 @@ structured_output do
 end
 ```
 
-Only primitive types are allowed with `of:`: `String`, `Integer`, `Float`, `TrueClass`, `FalseClass`.
+`of:` takes a primitive type: `String`, `Integer`, `Float`, `Riffer::Params::Boolean`, `TrueClass`, `FalseClass`.
+
+Add `enum:` to limit each item to a list of values:
+
+```ruby
+structured_output do
+  required :tags, Array, of: String, enum: %w[urgent billing technical]
+end
+```
+
+An item outside the list fails validation with its index: `tags[1] must be one of: urgent, billing, technical`.
+
+For an array of arrays, put the type in brackets. Each pair of brackets adds a level, and `enum:` and `format:` apply to the innermost items:
+
+```ruby
+structured_output do
+  required :rows, Array, of: [Integer], description: "Seat numbers, one array per row"
+  required :board, Array, of: [String], enum: %w[x o]
+end
+```
+
+A row that isn't an array fails validation with its index: `rows[1] must be an array`.
+
+#### Formats
+
+Use `format:` on a `String`, or on an `Array` whose innermost type is `String`, to require a standard string format:
+
+```ruby
+structured_output do
+  required :born_on, String, format: "date"
+  optional :email, String, format: "email"
+  required :visit_ids, Array, of: String, format: "uuid"
+end
+```
+
+Supported formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid`. Dates and times use RFC 3339 syntax, and a `time` may leave out its UTC offset. `email` and `hostname` are checked loosely, rejecting only values that are clearly not an address or a host name.
+
+A value that doesn't match fails validation, with its index on an array: `born_on must be a valid date`, `visit_ids[1] must be a valid uuid`. Values stay strings.
+
+A model that must match a format writes a matching value even when it has none, so it may invent an email. Make such a field `optional` so the model can return `null`.
 
 #### Arrays of Objects
 
@@ -270,9 +324,32 @@ structured_output do
 end
 ```
 
+#### Either/Or Shapes
+
+Use `Riffer::Params::AnyOf` when a field must be one of several object shapes. Each `variant` block defines one shape, the same way a `Hash` block does:
+
+```ruby
+structured_output do
+  required :result, Riffer::Params::AnyOf, description: "The address, or why none was found" do
+    variant do
+      required :street, String, description: "Street address"
+      required :city, String, description: "City"
+    end
+    variant do
+      required :error_code, String, enum: %w[no_address multiple_addresses]
+      required :error_message, String
+    end
+  end
+end
+```
+
+The schema sends the field as `anyOf`, with one object per variant. An answer must match one variant completely: every required field of that variant, and no field from outside it. Variants are tried in order and the first match is returned. When none match, the error lists each variant's problems: `result must match one of the variants: variant 1 (street is required, city is required), variant 2 (error_code is required, error_message is required)`.
+
+An optional `AnyOf` field can also be `null`.
+
 #### Limitations
 
-A `Hash` param requires a block, and an `Array` param requires a block or `of:`. Using both `of:` and a block raises `Riffer::ArgumentError`. Using `of:` with a non-primitive type (e.g. `of: Hash`) also raises `Riffer::ArgumentError`.
+A `Hash` param requires a block, and an `Array` param requires a block or `of:`. Using both `of:` and a block raises `Riffer::ArgumentError`. Using `of:` with a non-primitive type (e.g. `of: Hash` or `of: [Hash]`), or with more than one type (`of: [Integer, String]`), also raises `Riffer::ArgumentError`. An `AnyOf` param requires a block with at least two `variant`s, and can't be used with `of:` or `enum:`. Using `enum:` on a `Hash`, or on an `Array` without `of:`, also raises `Riffer::ArgumentError`. So does `format:` with an unsupported format, on a type other than `String` or an `Array` whose innermost type is `String`, or together with `enum:`.
 
 Structured output is not compatible with streaming — calling `stream` on an agent with structured output configured raises `Riffer::ArgumentError`.
 

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/OVERVIEW.md

@@ -39,7 +39,7 @@ See [Tools](TOOLS.md) for details.
 
 ### Structured Output
 
-Agents can return structured JSON responses that conform to a schema. The response is automatically parsed and validated. Schemas support nested objects (`Hash`), typed arrays (`Array, of:`), and arrays of objects (`Array` with block):
+Agents can return structured JSON responses that conform to a schema. The response is automatically parsed and validated. Schemas support nested objects (`Hash`), typed arrays (`Array, of:`), arrays of arrays (`Array, of: [Integer]`), arrays of objects (`Array` with block), and either/or shapes (`Riffer::Params::AnyOf`):
 
 ```ruby
 class SentimentAgent < Riffer::Agent

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/TOOLS.md

@@ -82,7 +82,8 @@ end
 Options:
 
 - `description` - Human-readable description for the LLM
-- `enum` - Array of allowed values
+- `enum` - Array of allowed values (for the innermost items of an `Array` with `of:`)
+- `format` - String format such as `"date"` or `"email"` (for the innermost `String` items of an `Array`; see [Formats](AGENTS.md#formats))
 
 ### optional
 
@@ -99,19 +100,21 @@ Options:
 
 - `description` - Human-readable description
 - `default` - Default value when not provided
-- `enum` - Array of allowed values
+- `enum` - Array of allowed values (for the innermost items of an `Array` with `of:`)
+- `format` - String format such as `"date"` or `"email"` (for the innermost `String` items of an `Array`; see [Formats](AGENTS.md#formats))
 
 ### Supported Types
 
-| Ruby Type                  | JSON Schema Type |
-| -------------------------- | ---------------- |
-| `String`                   | `string`         |
-| `Integer`                  | `integer`        |
-| `Float`                    | `number`         |
-| `Riffer::Params::Boolean`  | `boolean`        |
-| `TrueClass` / `FalseClass` | `boolean`        |
-| `Array`                    | `array`          |
-| `Hash`                     | `object`         |
+| Ruby Type                  | JSON Schema Type   |
+| -------------------------- | ------------------ |
+| `String`                   | `string`           |
+| `Integer`                  | `integer`          |
+| `Float`                    | `number`           |
+| `Riffer::Params::Boolean`  | `boolean`          |
+| `TrueClass` / `FalseClass` | `boolean`          |
+| `Array`                    | `array`            |
+| `Hash`                     | `object`           |
+| `Riffer::Params::AnyOf`    | `anyOf` of objects |
 
 `Riffer::Params::Boolean` is the preferred way to declare boolean parameters. `TrueClass` and `FalseClass` continue to work for backwards compatibility.
 
@@ -119,7 +122,7 @@ A `Float` param accepts a whole number too, since JSON Schema's `number` covers
 
 ### Nested Parameters
 
-Tool params support the same nested DSL as structured output — nested objects (`Hash` with block), typed arrays (`Array, of:`), and arrays of objects (`Array` with block). See the [structured output section in Agents](AGENTS.md#nested-objects) for full syntax.
+Tool params support the same nested DSL as structured output — nested objects (`Hash` with block), typed arrays (`Array, of:`), arrays of arrays (`Array, of: [Integer]`), arrays of objects (`Array` with block), and either/or shapes (`Riffer::Params::AnyOf` with `variant` blocks). See the [structured output section in Agents](AGENTS.md#nested-objects) for full syntax.
 
 ```ruby
 class CreateOrderTool < Riffer::Tool

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