riffer 0.53.0 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70784c56c20102b8da3e1e147bc843db2287e2be910f1e10d26b8ee9a2f8e0f9
-  data.tar.gz: 6df766acde899e39867a06de11fca0d013671e4bda34d3759b4ae310a43d04de
+  metadata.gz: da8c08b227ba3ddddaa025377b70f1dfb9acaa3c86b52ff9866446e8e908443c
+  data.tar.gz: 598cddab932d5f4e3c775847eafaba44d7d0fe21741539927fa1cad15cb1767e
 SHA512:
-  metadata.gz: 39af9afa9f695fe6dcc661915e1173ddf812db2ee425b83f77ee42d2080cea623b0f03f82c80ae606e7b4caf2f42bb3799a63ed0955ab7baa13b2c30861a2781
-  data.tar.gz: 1f79ef71cf1a838092444368f6986cd772803aeffe0de9acadc5cf8c23834e0e56c04e5049001eaeab3360d13a0eb3767a8118f429cacdbad7372879706ce332
+  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.53.0"
+  ".": "0.54.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,21 @@ 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)
 
 

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

@@ -212,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`.
 
@@ -249,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
 
@@ -285,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/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/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/providers/GEMINI.md

@@ -172,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/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/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

data/lib/riffer/params/format.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "date"
+require "ipaddr"
+
+module Riffer::Params::Format
+  extend self
+
+  DATE = /\A(\d{4})-(\d{2})-(\d{2})\z/ #: Regexp
+
+  DATE_TIME = /\A(\d{4})-(\d{2})-(\d{2})[Tt]([01]\d|2[0-3]):[0-5]\d:([0-5]\d|60)(\.\d+)?([Zz]|[+-]([01]\d|2[0-3]):[0-5]\d)\z/ #: Regexp
+
+  # The offset is optional: Anthropic's grammar emits times without one.
+  TIME = /\A([01]\d|2[0-3]):[0-5]\d:([0-5]\d|60)(\.\d+)?([Zz]|[+-]([01]\d|2[0-3]):[0-5]\d)?\z/ #: Regexp
+
+  DURATION = /\AP(?!\z)((\d+Y)?(\d+M)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?|\d+W)\z/ #: Regexp
+
+  UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/ #: Regexp
+
+  # The WHATWG HTML pattern: no single pattern matches RFC 5322 exactly, so
+  # this one only rules out values that are clearly not an address.
+  EMAIL = %r{\A[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*\z} #: Regexp
+
+  HOSTNAME = /\A(?=.{1,253}\.?\z)[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*\.?\z/ #: Regexp
+
+  # The formats OpenAI, Anthropic and Bedrock all accept. OpenAI rejects uri.
+  CHECKS = {
+    "date-time" => ->(value) { calendar_date?(DATE_TIME, value) },
+    "time" => ->(value) { TIME.match?(value) },
+    "date" => ->(value) { calendar_date?(DATE, value) },
+    "duration" => ->(value) { DURATION.match?(value) },
+    "email" => ->(value) { EMAIL.match?(value) },
+    "hostname" => ->(value) { HOSTNAME.match?(value) },
+    "ipv4" => ->(value) { ip_address?(value, &:ipv4?) },
+    "ipv6" => ->(value) { ip_address?(value, &:ipv6?) },
+    "uuid" => ->(value) { UUID.match?(value) },
+  }.freeze #: Hash[String, ^(String) -> bool]
+
+  private_constant :DATE, :DATE_TIME, :TIME, :DURATION, :UUID, :EMAIL, :HOSTNAME, :CHECKS
+
+  NAMES = CHECKS.keys.freeze #: Array[String]
+
+  #--
+  #: (String, String) -> bool
+  def valid?(format, value)
+    CHECKS.fetch(format).call(value)
+  end
+
+  private
+
+  #--
+  #: (Regexp, String) -> bool
+  def calendar_date?(pattern, value)
+    match = pattern.match(value)
+    return false unless match
+
+    # RFC 3339 dates are proleptic Gregorian; Date defaults to the Julian calendar before 1582.
+    Date.valid_date?(match[1].to_i, match[2].to_i, match[3].to_i, Date::GREGORIAN)
+  end
+
+  #--
+  #: (String) { (IPAddr) -> bool } -> bool
+  def ip_address?(value)
+    # IPAddr also accepts a prefix (10.0.0.0/24), a zone ID (fe80::1%eth0) and
+    # brackets ([::1]), none of which are part of an address.
+    return false if value.match?(%r{[/%\[\]]})
+
+    yield IPAddr.new(value)
+  rescue IPAddr::Error
+    false
+  end
+end

data/lib/riffer/params/param.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
+require "json"
+
 class Riffer::Params::Param
   TYPE_MAPPINGS = {
     String => "string",
@@ -34,43 +36,99 @@ class Riffer::Params::Param
 
   attr_reader :enum #: Array[untyped]? # @dynamic enum
 
+  attr_reader :format #: String? # @dynamic format
+
   attr_reader :default #: untyped # @dynamic default
 
   attr_reader :item_type #: Module? # @dynamic item_type
 
+  attr_reader :dimensions #: Integer # @dynamic dimensions
+
   attr_reader :nested_params #: Riffer::Params? # @dynamic nested_params
 
+  attr_reader :variants #: Array[Riffer::Params]? # @dynamic variants
+
   #--
   #: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
   def self.from_json_schema(name, schema, required:)
-    ruby_type = json_type_to_ruby(schema[:type])
-    item_type, nested = resolve_nesting(ruby_type, schema)
+    variants = resolve_variants(schema[:anyOf]) if schema.key?(:anyOf)
+    ruby_type = variants ? Riffer::Params::AnyOf : json_type_to_ruby(schema[:type])
+    nested = resolve_nested_params(ruby_type, schema)
+    item_type, dimensions, items = resolve_typed_items(schema) if ruby_type == Array && !nested
 
     new(
       name: name,
       type: ruby_type,
       required: required,
       description: schema[:description],
-      enum: schema[:enum],
+      enum: schema[:enum] || items&.dig(:enum),
+      format: schema[:format] || items&.dig(:format),
       default: schema[:default],
       item_type: item_type,
+      dimensions: dimensions || 1,
       nested_params: nested,
+      variants: variants,
     )
   end
 
   #--
-  #: (Module, Hash[Symbol, untyped]) -> [Module?, Riffer::Params?]
-  def self.resolve_nesting(ruby_type, schema)
-    return [nil, Riffer::Params.from_json_schema(schema)] if ruby_type == Hash && schema[:properties]
-    return [nil, nil] unless ruby_type == Array
+  #: (Array[Hash[Symbol, untyped]]) -> Array[Riffer::Params]
+  def self.resolve_variants(branches)
+    # Strict schemas add a null branch to optional fields; nullability comes from +required+.
+    variants = branches.reject { |branch| branch[:type] == "null" }.map do |branch|
+      raise Riffer::ArgumentError, "Unsupported anyOf branch: #{branch.to_json}" unless branch[:type] == "object"
 
+      Riffer::Params.from_json_schema(branch)
+    end
+    raise Riffer::ArgumentError, "anyOf requires at least two object branches" if variants.size < 2
+
+    variants
+  end
+  private_class_method :resolve_variants
+
+  #--
+  #: (Module, Hash[Symbol, untyped]) -> Riffer::Params?
+  def self.resolve_nested_params(ruby_type, schema)
+    if ruby_type == Hash && schema[:properties]
+      Riffer::Params.from_json_schema(schema)
+    elsif ruby_type == Array && schema[:items].is_a?(Hash) && schema[:items][:properties]
+      Riffer::Params.from_json_schema(schema[:items])
+    end
+  end
+  private_class_method :resolve_nested_params
+
+  #--
+  #: (Hash[Symbol, untyped]) -> [Module, Integer, Hash[Symbol, untyped]]?
+  def self.resolve_typed_items(schema)
     items = schema[:items]
-    return [nil, nil] unless items.is_a?(Hash)
-    return [nil, Riffer::Params.from_json_schema(items)] if items[:properties]
+    return unless items.is_a?(Hash)
 
-    [json_type_to_ruby(items[:type]), nil]
+    dimensions = 1
+    # Riffer only writes nested arrays with enum/format and a single primitive type on the innermost
+    # items, and no nullable inner arrays; any other shape would read back with a different meaning.
+    while json_type_to_ruby(items[:type]) == Array
+      inner = items[:items]
+      unless items[:type] == "array" && inner.is_a?(Hash) && !items.keys.intersect?(%i[enum format])
+        raise Riffer::ArgumentError, "Unsupported nested array: #{items.to_json}"
+      end
+
+      items = inner
+      dimensions += 1
+    end
+
+    item_type = json_type_to_ruby(items[:type])
+    if dimensions > 1
+      if schema.keys.intersect?(%i[enum format])
+        raise Riffer::ArgumentError, "Unsupported nested array: #{schema.to_json}"
+      end
+      unless items[:type].is_a?(String) && PRIMITIVE_TYPES.include?(item_type)
+        raise Riffer::ArgumentError, "Unsupported nested array items: #{items.to_json}"
+      end
+    end
+
+    [item_type, dimensions, items]
   end
-  private_class_method :resolve_nesting
+  private_class_method :resolve_typed_items
 
   #--
   #: (untyped) -> Module
@@ -81,16 +139,27 @@ class Riffer::Params::Param
   private_class_method :json_type_to_ruby
 
   #--
-  #: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Module?, ?nested_params: Riffer::Params?) -> void
-  def initialize(name:, type:, required:, description: nil, enum: nil, default: nil, item_type: nil, nested_params: nil)
+  #: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?item_type: Module?, ?dimensions: Integer, ?nested_params: Riffer::Params?, ?variants: Array[Riffer::Params]?) -> void
+  def initialize(name:, type:, required:, description: nil, enum: nil, format: nil, default: nil, item_type: nil,
+                 dimensions: 1, nested_params: nil, variants: nil)
+    if type == Riffer::Params::AnyOf && variants.nil?
+      raise Riffer::ArgumentError, "#{name}: an AnyOf param requires variants"
+    end
+
     @name = name.to_sym
     @type = type
     @required = required
     @description = description
     @enum = enum
+    # Frozen and deduplicated, so copies never share a mutable string.
+    @format = format.is_a?(String) ? -format : format
     @default = default
     @item_type = item_type
+    @dimensions = dimensions
     @nested_params = nested_params
+    @variants = variants
+    # Checked here rather than in Params so from_json_schema enforces it too.
+    validate_format! if format
   end
 
   #--
@@ -102,6 +171,8 @@ class Riffer::Params::Param
       [true, false].include?(value)
     elsif type == Float
       value.is_a?(Numeric)
+    elsif type == Riffer::Params::AnyOf
+      value.is_a?(Hash)
     else
       value.is_a?(type)
     end
@@ -110,6 +181,8 @@ class Riffer::Params::Param
   #--
   #: () -> String
   def type_name
+    return "object" if type == Riffer::Params::AnyOf
+
     TYPE_MAPPINGS[type] || type.to_s.downcase
   end
 
@@ -120,9 +193,21 @@ class Riffer::Params::Param
     # Nullable so strict providers can distinguish absent from present.
     nullable = strict && !required
 
+    if type == Riffer::Params::AnyOf && variants
+      schema = { anyOf: variants.map { |variant| variant.to_json_schema(strict: strict) } } #: Hash[Symbol, untyped]
+      schema[:anyOf] << { type: "null" } if nullable
+      schema[:description] = description if description
+      schema[:default] = default unless strict || default.nil?
+      return schema
+    end
+
+    # A typed array's enum and format constrain its items, not the array.
+    value_enum = enum unless item_type
+    value_format = format unless item_type
+
     # Providers like Anthropic reject a nullable type union combined with enum.
-    if nullable && enum
-      schema = { anyOf: [{ type: type_name, enum: enum }, { type: "null" }] } #: Hash[Symbol, untyped]
+    if nullable && value_enum
+      schema = { anyOf: [{ type: type_name, enum: value_enum }, { type: "null" }] } #: Hash[Symbol, untyped]
       schema[:description] = description if description
       return schema
     end
@@ -132,7 +217,8 @@ class Riffer::Params::Param
 
     schema = { type: type } #: Hash[Symbol, untyped]
     schema[:description] = description if description
-    schema[:enum] = enum if enum
+    schema[:enum] = value_enum if value_enum
+    schema[:format] = value_format if value_format
     # Strict providers reject the +default+ keyword; emit it only in
     # non-strict mode, where it makes the schema a lossless round-trip
     # source for +from_json_schema+.
@@ -141,7 +227,9 @@ class Riffer::Params::Param
     if self.type == Array && nested_params
       schema[:items] = nested_params.to_json_schema(strict: strict)
     elsif self.type == Array && item_type
-      schema[:items] = { type: TYPE_MAPPINGS[item_type] }
+      items = { type: TYPE_MAPPINGS[item_type], enum: enum, format: format }.compact #: Hash[Symbol, untyped]
+      (dimensions - 1).times { items = { type: "array", items: items } }
+      schema[:items] = items
     elsif self.type == Hash && nested_params
       # The nested schema carries its own type: "object", which would clobber a nullable union.
       schema.merge!(nested_params.to_json_schema(strict: strict).except(:type))
@@ -160,10 +248,25 @@ class Riffer::Params::Param
   def initialize_copy(source)
     super
     @nested_params = source.nested_params&.dup
+    @variants = source.variants&.map(&:dup)
     @enum = Riffer::Helpers::DeepDup.call(source.enum)
     @default = Riffer::Helpers::DeepDup.call(source.default)
   end
 
+  #--
+  #: () -> void
+  def validate_format!
+    unless Riffer::Params::Format::NAMES.include?(format)
+      raise Riffer::ArgumentError,
+            "#{name}: format: must be a supported format (#{Riffer::Params::Format::NAMES.join(', ')}), " \
+            "got #{format.inspect}"
+    end
+    unless type == String || (type == Array && item_type == String)
+      raise Riffer::ArgumentError, "#{name}: format: requires a String or an Array whose innermost type is String"
+    end
+    raise Riffer::ArgumentError, "#{name}: format: cannot be used with enum:" if enum
+  end
+
   #--
   #: () -> void
   def validate_strict_shape!

data/lib/riffer/params.rb

@@ -29,33 +29,45 @@ class Riffer::Params
   end
 
   #--
-  #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
-  def required(name, type, description: nil, enum: nil, of: nil, &)
-    nested = build_nested(type, of, &)
+  #: (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
+  #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def required(name, type, description: nil, enum: nil, format: nil, of: nil, &)
+    item_type, dimensions = unwrap_of(of)
+    nested = build_nested(type, item_type, enum, &) unless type == Riffer::Params::AnyOf
+    variants = build_variants(of, enum, &) if type == Riffer::Params::AnyOf
     @parameters << Riffer::Params::Param.new(
       name: name,
       type: type,
       required: true,
       description: description,
       enum: enum,
-      item_type: of,
+      format: format,
+      item_type: item_type,
+      dimensions: dimensions,
       nested_params: nested,
+      variants: variants,
     )
   end
 
   #--
-  #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
-  def optional(name, type, description: nil, enum: nil, default: nil, of: nil, &)
-    nested = build_nested(type, of, &)
+  #: (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?, ?default: untyped) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
+  #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def optional(name, type, description: nil, enum: nil, format: nil, default: nil, of: nil, &)
+    item_type, dimensions = unwrap_of(of)
+    nested = build_nested(type, item_type, enum, &) unless type == Riffer::Params::AnyOf
+    variants = build_variants(of, enum, &) if type == Riffer::Params::AnyOf
     @parameters << Riffer::Params::Param.new(
       name: name,
       type: type,
       required: false,
       description: description,
       enum: enum,
+      format: format,
       default: default,
-      item_type: of,
+      item_type: item_type,
+      dimensions: dimensions,
       nested_params: nested,
+      variants: variants,
     )
   end
 
@@ -83,11 +95,17 @@ class Riffer::Params
         next
       end
 
-      if param.enum && !param.enum.include?(value)
+      # A typed array's enum and format constrain its items, which validate_typed_array checks.
+      if param.enum && !param.item_type && !param.enum.include?(value)
         errors << "#{param.name} must be one of: #{param.enum.join(', ')}"
         next
       end
 
+      if param.format && !param.item_type && !Riffer::Params::Format.valid?(param.format, value)
+        errors << "#{param.name} must be a valid #{param.format}"
+        next
+      end
+
       value = validate_nested(param, value, errors)
 
       validated[param.name] = coerce_value(param.type, value)
@@ -131,9 +149,20 @@ class Riffer::Params
   end
 
   #--
-  #: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
-  def build_nested(type, of, &block)
+  #: ((Module | Array[untyped])?, ?Integer) -> [Module?, Integer]
+  def unwrap_of(of, dimensions = 1)
+    return [of, dimensions] unless of.is_a?(Array)
+    raise Riffer::ArgumentError, "of: must nest exactly one type, got #{of.inspect}" unless of.size == 1 && of.first
+
+    unwrap_of(of.first, dimensions + 1)
+  end
+
+  #--
+  #: (Module, Module?, Array[untyped]?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
+  def build_nested(type, of, enum, &block)
     raise Riffer::ArgumentError, "cannot use both of: and a block" if of && block
+    raise Riffer::ArgumentError, "enum: cannot be used with Hash" if enum && type == Hash
+    raise Riffer::ArgumentError, "enum: with Array requires of:" if enum && type == Array && !of
 
     if of
       raise Riffer::ArgumentError, "of: can only be used with Array type, got #{type}" unless type == Array
@@ -155,10 +184,26 @@ class Riffer::Params
     nested
   end
 
+  #--
+  #: ((Module | Array[untyped])?, Array[untyped]?) ?{ (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> Array[Riffer::Params]
+  def build_variants(of, enum, &block)
+    raise Riffer::ArgumentError, "of: cannot be used with AnyOf" if of
+    raise Riffer::ArgumentError, "enum: cannot be used with AnyOf" if enum
+    raise Riffer::ArgumentError, "AnyOf requires a block defining its variants" unless block
+
+    any_of = Riffer::Params::AnyOf.new
+    any_of.instance_eval(&block)
+    raise Riffer::ArgumentError, "AnyOf requires at least two variants" if any_of.variants.size < 2
+
+    any_of.variants
+  end
+
   #--
   #: (Riffer::Params::Param, untyped, Array[String]) -> untyped
   def validate_nested(param, value, errors)
-    if param.type == Hash && param.nested_params
+    if param.type == Riffer::Params::AnyOf
+      validate_any_of(param, value, errors)
+    elsif param.type == Hash && param.nested_params
       validate_nested_hash(param, value, errors)
     elsif param.type == Array && param.nested_params
       validate_nested_array_of_objects(param, value, errors)
@@ -183,6 +228,49 @@ class Riffer::Params
     value
   end
 
+  #--
+  #: (Riffer::Params::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+  def validate_any_of(param, value, errors)
+    variants = param.variants
+    return value unless variants
+
+    variant_errors = [] #: Array[String]
+    variants.each.with_index(1) do |variant, number|
+      validated = variant.validate(value)
+      # Each variant's schema sets additionalProperties: false on every object
+      # it declares, so a key outside this variant rules it out.
+      unknown = undeclared_keys(value, validated)
+      return validated if unknown.empty?
+
+      variant_errors << "variant #{number} (#{unknown.map { |path| "#{path} is not allowed" }.join(', ')})"
+    rescue Riffer::ValidationError => e
+      # Enclosing params split errors on "; " to prefix their path, so one
+      # variant's errors must not contain it.
+      variant_errors << "variant #{number} (#{e.message.gsub('; ', ', ')})"
+    end
+
+    errors << "#{param.name} must match one of the variants: #{variant_errors.join(', ')}"
+    value
+  end
+
+  # Validation drops keys a Params doesn't declare, at any depth, so they are
+  # the keys in the input that are missing from the output.
+  #--
+  #: (untyped, untyped, ?String?) -> Array[String]
+  def undeclared_keys(value, validated, path = nil)
+    case value
+    when Hash
+      value.flat_map do |key, child|
+        key_path = [path, key].compact.join(".")
+        validated.key?(key) ? undeclared_keys(child, validated[key], key_path) : [key_path]
+      end
+    when Array
+      value.each_with_index.flat_map { |item, i| undeclared_keys(item, validated[i], "#{path}[#{i}]") }
+    else
+      []
+    end
+  end
+
   #--
   #: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
   def validate_nested_array_of_objects(param, value, errors)
@@ -204,22 +292,33 @@ class Riffer::Params
   end
 
   #--
-  #: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
-  def validate_typed_array(param, value, errors)
+  #: (Riffer::Params::Param, Array[untyped], Array[String], ?String, ?Integer) -> Array[untyped]
+  def validate_typed_array(param, value, errors, path = param.name.to_s, dimensions = param.dimensions)
     item_type = param.item_type
     return value unless item_type
 
-    type_name = Riffer::Params::Param::TYPE_MAPPINGS[item_type]
-    valid_item = if [Riffer::Params::Boolean, TrueClass, FalseClass].include?(item_type)
-                   ->(item) { [true, false].include?(item) }
-                 elsif item_type == Float
-                   ->(item) { item.is_a?(Numeric) }
-                 else
-                   ->(item) { item.is_a?(item_type) }
-                 end
     value.map.with_index do |item, i|
-      unless valid_item.call(item)
-        errors << "#{param.name}[#{i}] must be a #{type_name}"
+      item_path = "#{path}[#{i}]"
+
+      if dimensions > 1
+        next validate_typed_array(param, item, errors, item_path, dimensions - 1) if item.is_a?(Array)
+
+        errors << "#{item_path} must be an array"
+        next item
+      end
+
+      unless valid_item?(item_type, item)
+        errors << "#{item_path} must be a #{Riffer::Params::Param::TYPE_MAPPINGS[item_type]}"
+        next item
+      end
+
+      if param.enum && !param.enum.include?(item)
+        errors << "#{item_path} must be one of: #{param.enum.join(', ')}"
+        next item
+      end
+
+      if param.format && !Riffer::Params::Format.valid?(param.format, item)
+        errors << "#{item_path} must be a valid #{param.format}"
         next item
       end
 
@@ -227,6 +326,18 @@ class Riffer::Params
     end
   end
 
+  #--
+  #: (Module, untyped) -> bool
+  def valid_item?(type, item)
+    if [Riffer::Params::Boolean, TrueClass, FalseClass].include?(type)
+      [true, false].include?(item)
+    elsif type == Float
+      item.is_a?(Numeric)
+    else
+      item.is_a?(type)
+    end
+  end
+
   #--
   #: (Module, untyped) -> untyped
   def coerce_value(type, value)

data/lib/riffer/providers/base.rb

@@ -38,7 +38,7 @@ class Riffer::Providers::Base
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
     Riffer::Files::Resolver.new(provider: self).resolve!(messages)
-    messages = merge_consecutive_messages(with_structured_output_prompt(messages, options[:structured_output]))
+    messages = with_structured_output_prompt(merge_consecutive_messages(messages), options[:structured_output])
     options = apply_reasoning(model, options)
     params = build_request_params(messages, model, request_options(options))
 
@@ -77,7 +77,7 @@ class Riffer::Providers::Base
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
     Riffer::Files::Resolver.new(provider: self).resolve!(messages)
-    messages = merge_consecutive_messages(with_structured_output_prompt(messages, options[:structured_output]))
+    messages = with_structured_output_prompt(merge_consecutive_messages(messages), options[:structured_output])
     options = apply_reasoning(model, options)
     params = build_request_params(messages, model, request_options(options))
 
@@ -427,13 +427,13 @@ class Riffer::Providers::Base
   def with_structured_output_prompt(messages, structured_output)
     return messages unless structured_output&.prompted?
 
-    # After the leading system messages, so merge_consecutive_messages folds it into the system prompt.
-    leading_system = messages.take_while { |m| m.is_a?(Riffer::Messages::System) }
-    [
-      *leading_system,
-      Riffer::Messages::System.new(structured_output.prompt_instructions),
-      *messages.drop(leading_system.length),
-    ]
+    # Models follow the schema more reliably at the end of each user turn than in the system prompt.
+    instructions = structured_output.prompt_instructions
+    messages.map do |message|
+      next message unless message.is_a?(Riffer::Messages::User)
+
+      Riffer::Messages::User.new("#{message.content}\n\n#{instructions}", id: message.id, files: message.files)
+    end
   end
 
   #--

data/lib/riffer/providers/gemini.rb

@@ -340,6 +340,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     end
 
     schema[:items] = strip_additional_properties(schema[:items]) if schema[:items].is_a?(Hash)
+    schema[:anyOf] = schema[:anyOf].map { |branch| strip_additional_properties(branch) } if schema[:anyOf]
 
     schema
   end

data/lib/riffer/version.rb

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

data/rbs_collection.lock.yaml

@@ -77,6 +77,10 @@ gems:
     revision: 3913b7dffb65bdffdfe5cb9095108f932e85433b
     remote: https://github.com/ruby/gem_rbs_collection.git
     repo_dir: gems
+- name: date
+  version: '0'
+  source:
+    type: stdlib
 - name: dbm
   version: '0'
   source:
@@ -125,6 +129,10 @@ gems:
   version: '0'
   source:
     type: stdlib
+- name: ipaddr
+  version: '0'
+  source:
+    type: stdlib
 - name: json
   version: '0'
   source:

data/rbs_collection.yaml

@@ -10,3 +10,5 @@ path: .gem_rbs_collection
 gems:
   - name: yaml
   - name: cgi
+  - name: date
+  - name: ipaddr

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

@@ -25,4 +25,10 @@ class Riffer::Agent::StructuredOutput
   # --
   # : (String) -> Riffer::Agent::StructuredOutput::Result
   def parse_and_validate: (String) -> Riffer::Agent::StructuredOutput::Result
+
+  private
+
+  # --
+  # : (Hash[Symbol, untyped]) -> untyped
+  def placeholder: (Hash[Symbol, untyped]) -> untyped
 end

data/sig/generated/riffer/params/any_of.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/riffer/params/any_of.rb with RBS::Inline
+
+class Riffer::Params::AnyOf
+  attr_reader variants: Array[Riffer::Params]
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def variant: () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+end

data/sig/generated/riffer/params/format.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/riffer/params/format.rb with RBS::Inline
+
+module Riffer::Params::Format
+  DATE: Regexp
+
+  DATE_TIME: Regexp
+
+  # The offset is optional: Anthropic's grammar emits times without one.
+  TIME: Regexp
+
+  DURATION: Regexp
+
+  UUID: Regexp
+
+  # The WHATWG HTML pattern: no single pattern matches RFC 5322 exactly, so
+  # this one only rules out values that are clearly not an address.
+  EMAIL: Regexp
+
+  HOSTNAME: Regexp
+
+  # The formats OpenAI, Anthropic and Bedrock all accept. OpenAI rejects uri.
+  CHECKS: Hash[String, ^(String) -> bool]
+
+  NAMES: Array[String]
+
+  # --
+  # : (String, String) -> bool
+  def valid?: (String, String) -> bool
+
+  private
+
+  # --
+  # : (Regexp, String) -> bool
+  def calendar_date?: (Regexp, String) -> bool
+
+  # --
+  # : (String) { (IPAddr) -> bool } -> bool
+  def ip_address?: (String) { (IPAddr) -> bool } -> bool
+end

data/sig/generated/riffer/params/param.rbs

@@ -17,27 +17,41 @@ class Riffer::Params::Param
 
   attr_reader enum: Array[untyped]?
 
+  attr_reader format: String?
+
   attr_reader default: untyped
 
   attr_reader item_type: Module?
 
+  attr_reader dimensions: Integer
+
   attr_reader nested_params: Riffer::Params?
 
+  attr_reader variants: Array[Riffer::Params]?
+
   # --
   # : (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
   def self.from_json_schema: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
 
   # --
-  # : (Module, Hash[Symbol, untyped]) -> [Module?, Riffer::Params?]
-  def self.resolve_nesting: (Module, Hash[Symbol, untyped]) -> [ Module?, Riffer::Params? ]
+  # : (Array[Hash[Symbol, untyped]]) -> Array[Riffer::Params]
+  def self.resolve_variants: (Array[Hash[Symbol, untyped]]) -> Array[Riffer::Params]
+
+  # --
+  # : (Module, Hash[Symbol, untyped]) -> Riffer::Params?
+  def self.resolve_nested_params: (Module, Hash[Symbol, untyped]) -> Riffer::Params?
+
+  # --
+  # : (Hash[Symbol, untyped]) -> [Module, Integer, Hash[Symbol, untyped]]?
+  def self.resolve_typed_items: (Hash[Symbol, untyped]) -> [ Module, Integer, Hash[Symbol, untyped] ]?
 
   # --
   # : (untyped) -> Module
   def self.json_type_to_ruby: (untyped) -> Module
 
   # --
-  # : (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Module?, ?nested_params: Riffer::Params?) -> void
-  def initialize: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Module?, ?nested_params: Riffer::Params?) -> void
+  # : (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?item_type: Module?, ?dimensions: Integer, ?nested_params: Riffer::Params?, ?variants: Array[Riffer::Params]?) -> void
+  def initialize: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?item_type: Module?, ?dimensions: Integer, ?nested_params: Riffer::Params?, ?variants: Array[Riffer::Params]?) -> void
 
   # --
   # : (untyped) -> bool
@@ -60,6 +74,10 @@ class Riffer::Params::Param
   # : (Riffer::Params::Param) -> void
   def initialize_copy: (Riffer::Params::Param) -> void
 
+  # --
+  # : () -> void
+  def validate_format!: () -> void
+
   # --
   # : () -> void
   def validate_strict_shape!: () -> void

data/sig/generated/riffer/params.rbs

@@ -14,12 +14,16 @@ class Riffer::Params
   def self.from_json_schema: (Hash[Symbol, untyped]) -> Riffer::Params
 
   # --
-  # : (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
-  def required: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  # : (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
+  # : (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def required: (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
+              | (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
 
   # --
-  # : (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
-  def optional: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  # : (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?, ?default: untyped) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
+  # : (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def optional: (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?, ?default: untyped) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
+              | (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
 
   # --
   # : (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -38,8 +42,16 @@ class Riffer::Params
   def initialize_copy: (Riffer::Params) -> void
 
   # --
-  # : (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
-  def build_nested: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
+  # : ((Module | Array[untyped])?, ?Integer) -> [Module?, Integer]
+  def unwrap_of: ((Module | Array[untyped])?, ?Integer) -> [ Module?, Integer ]
+
+  # --
+  # : (Module, Module?, Array[untyped]?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
+  def build_nested: (Module, Module?, Array[untyped]?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
+
+  # --
+  # : ((Module | Array[untyped])?, Array[untyped]?) ?{ (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> Array[Riffer::Params]
+  def build_variants: ((Module | Array[untyped])?, Array[untyped]?) ?{ (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> Array[Riffer::Params]
 
   # --
   # : (Riffer::Params::Param, untyped, Array[String]) -> untyped
@@ -49,13 +61,27 @@ class Riffer::Params
   # : (Riffer::Params::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
   def validate_nested_hash: (Riffer::Params::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
 
+  # --
+  # : (Riffer::Params::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+  def validate_any_of: (Riffer::Params::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+
+  # Validation drops keys a Params doesn't declare, at any depth, so they are
+  # the keys in the input that are missing from the output.
+  # --
+  # : (untyped, untyped, ?String?) -> Array[String]
+  def undeclared_keys: (untyped, untyped, ?String?) -> Array[String]
+
   # --
   # : (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
   def validate_nested_array_of_objects: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
 
   # --
-  # : (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
-  def validate_typed_array: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
+  # : (Riffer::Params::Param, Array[untyped], Array[String], ?String, ?Integer) -> Array[untyped]
+  def validate_typed_array: (Riffer::Params::Param, Array[untyped], Array[String], ?String, ?Integer) -> Array[untyped]
+
+  # --
+  # : (Module, untyped) -> bool
+  def valid_item?: (Module, untyped) -> bool
 
   # --
   # : (Module, untyped) -> untyped

data/sig/manifest.yaml

@@ -1,4 +1,5 @@
 dependencies:
   - name: uri
   - name: net-http
-  - name: digest
+  - name: digest
+  - name: ipaddr

data/sig/manual/riffer/params/format.rbs

@@ -0,0 +1,5 @@
+# `Riffer::Params::Format` uses `extend self`; rbs-inline doesn't emit that,
+# so re-extend here to expose its instance methods as singleton methods.
+module Riffer::Params::Format
+  extend ::Riffer::Params::Format
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.53.0
+  version: 0.54.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -177,7 +177,9 @@ files:
 - lib/riffer/messages/user.rb
 - lib/riffer/messages/user/file_part.rb
 - lib/riffer/params.rb
+- lib/riffer/params/any_of.rb
 - lib/riffer/params/boolean.rb
+- lib/riffer/params/format.rb
 - lib/riffer/params/param.rb
 - lib/riffer/providers.rb
 - lib/riffer/providers/amazon_bedrock.rb
@@ -327,7 +329,9 @@ files:
 - sig/generated/riffer/messages/user.rbs
 - sig/generated/riffer/messages/user/file_part.rbs
 - sig/generated/riffer/params.rbs
+- sig/generated/riffer/params/any_of.rbs
 - sig/generated/riffer/params/boolean.rbs
+- sig/generated/riffer/params/format.rbs
 - sig/generated/riffer/params/param.rbs
 - sig/generated/riffer/providers.rbs
 - sig/generated/riffer/providers/amazon_bedrock.rbs
@@ -407,6 +411,7 @@ files:
 - sig/manual/riffer/mcp/authenticated_tool.rbs
 - sig/manual/riffer/mcp/registry.rbs
 - sig/manual/riffer/mcp/tool_factory.rbs
+- sig/manual/riffer/params/format.rbs
 - sig/manual/riffer/providers.rbs
 - sig/manual/riffer/providers/repository.rbs
 - sig/manual/riffer/testing.rbs