riffer 0.52.1 → 0.54.0

data/lib/riffer/providers/base.rb

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

data/lib/riffer/providers/gemini.rb

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

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

data/lib/riffer/providers/open_ai.rb

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

data/lib/riffer/providers/open_router.rb

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

data/lib/riffer/version.rb

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

data/lib/riffer.rb

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

data/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/config.rbs

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

data/sig/generated/riffer/agent/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/agent.rbs

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

data/sig/generated/riffer/{config/pricing → catalog}/rates.rbs

@@ -1,6 +1,6 @@
-# Generated from lib/riffer/config/pricing/rates.rb with RBS::Inline
+# Generated from lib/riffer/catalog/rates.rb with RBS::Inline
 
-class Riffer::Config::Pricing::Rates
+class Riffer::Catalog::Rates
   attr_reader input: Float
 
   attr_reader output: Float
@@ -10,10 +10,16 @@ class Riffer::Config::Pricing::Rates
   attr_reader cache_write: Float?
 
   # --
-  # : (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
-  def initialize: (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
+  # : (input: untyped, output: untyped, ?cache_read: untyped, ?cache_write: untyped) -> void
+  def initialize: (input: untyped, output: untyped, ?cache_read: untyped, ?cache_write: untyped) -> void
 
   # --
   # : (input_tokens: Integer, output_tokens: Integer, ?cache_read_tokens: Integer?, ?cache_write_tokens: Integer?) -> Float
   def cost_for: (input_tokens: Integer, output_tokens: Integer, ?cache_read_tokens: Integer?, ?cache_write_tokens: Integer?) -> Float
+
+  private
+
+  # --
+  # : (untyped, String) -> Float
+  def coerce_rate: (untyped, String) -> Float
 end

data/sig/generated/riffer/catalog.rbs

@@ -0,0 +1,77 @@
+# Generated from lib/riffer/catalog.rb with RBS::Inline
+
+class Riffer::Catalog
+  SUPPORTED_VERSIONS: Array[Integer]
+
+  FILE_KEYS: Array[String]
+
+  ENTRY_KEYS: Array[String]
+
+  PRICING_KEYS: Array[String]
+
+  @aliases: Hash[String, String]
+
+  @models: Hash[String, Hash[Symbol, untyped]]
+
+  # --
+  # : (Array[String]) -> Riffer::Catalog
+  def self.load: (Array[String]) -> Riffer::Catalog
+
+  # --
+  # : (models: Hash[String, Hash[Symbol, untyped]], aliases: Hash[String, String]) -> void
+  def initialize: (models: Hash[String, Hash[Symbol, untyped]], aliases: Hash[String, String]) -> void
+
+  # --
+  # : (String, Symbol) -> Hash[Symbol, untyped]?
+  def reasoning_options: (String, Symbol) -> Hash[Symbol, untyped]?
+
+  # --
+  # : (String) -> Riffer::Catalog::Rates?
+  def rates_for: (String) -> Riffer::Catalog::Rates?
+
+  # --
+  # : () -> bool
+  def empty?: () -> bool
+
+  # --
+  # : (String) -> Hash[String, Hash[Symbol, untyped]]
+  def self.parse_file: (String) -> Hash[String, Hash[Symbol, untyped]]
+
+  # --
+  # : (String, String, untyped) -> Hash[Symbol, untyped]
+  def self.parse_entry: (String, String, untyped) -> Hash[Symbol, untyped]
+
+  # --
+  # : (String, String, untyped) -> Array[String]
+  def self.parse_aliases: (String, String, untyped) -> Array[String]
+
+  # --
+  # : (String, String, untyped) -> Riffer::Catalog::Rates
+  def self.parse_pricing: (String, String, untyped) -> Riffer::Catalog::Rates
+
+  # --
+  # : (String, String, untyped) -> Hash[Symbol, Hash[Symbol, untyped]]
+  def self.parse_reasoning: (String, String, untyped) -> Hash[Symbol, Hash[Symbol, untyped]]
+
+  # --
+  # : (String, untyped, String) -> void
+  def self.validate_model_key!: (String, untyped, String) -> void
+
+  # --
+  # : (untyped) -> untyped
+  def self.symbolize_keys: (untyped) -> untyped
+
+  # --
+  # : (String, String) -> bot
+  def self.fail_load!: (String, String) -> bot
+
+  private
+
+  # --
+  # : (String) -> Hash[Symbol, untyped]?
+  def entry: (String) -> Hash[Symbol, untyped]?
+
+  # --
+  # : (untyped) -> untyped
+  def deep_freeze: (untyped) -> untyped
+end

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

@@ -1,7 +1,13 @@
 # Generated from lib/riffer/config/pricing.rb with RBS::Inline
 
+# @deprecated Set pricing in a catalog file instead (see docs/CATALOG.md).
+# A catalog entry's pricing wins over rates registered here.
 class Riffer::Config::Pricing
-  @rates: Hash[String, Riffer::Config::Pricing::Rates]
+  DEPRECATION_MESSAGE: String
+
+  @rates: Hash[String, Riffer::Catalog::Rates]
+
+  self.@warned: bool
 
   # --
   # : () -> void
@@ -12,20 +18,15 @@ class Riffer::Config::Pricing
   def set: (String | Array[String], input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
 
   # --
-  # : (String) -> Riffer::Config::Pricing::Rates?
-  def rates_for: (String) -> Riffer::Config::Pricing::Rates?
+  # : (String) -> Riffer::Catalog::Rates?
+  def rates_for: (String) -> Riffer::Catalog::Rates?
 
   # --
   # : () -> bool
   def empty?: () -> bool
 
-  private
-
+  # Once per process, so a boot that sets many models logs one line.
   # --
-  # : (untyped, String) -> Float
-  def coerce_rate: (untyped, String) -> Float
-
-  # --
-  # : (untyped, String) -> Float?
-  def coerce_optional_rate: (untyped, String) -> Float?
+  # : () -> void
+  def self.warn_deprecated: () -> void
 end

data/sig/generated/riffer/config.rbs

@@ -3,6 +3,8 @@
 class Riffer::Config
   VALID_MESSAGE_ID_STRATEGIES: untyped
 
+  @catalog: Riffer::Catalog?
+
   attr_reader amazon_bedrock: Riffer::Config::AmazonBedrock
 
   attr_reader anthropic: Riffer::Config::Anthropic
@@ -31,8 +33,23 @@ class Riffer::Config
 
   attr_reader files: Riffer::Config::Files
 
+  # @deprecated Use +catalog_files+.
   attr_reader pricing: Riffer::Config::Pricing
 
+  attr_reader catalog_files: Array[String]
+
+  # --
+  # : (Array[untyped]) -> void
+  def catalog_files=: (Array[untyped]) -> void
+
+  # --
+  # : () -> Riffer::Catalog
+  def catalog: () -> Riffer::Catalog
+
+  # --
+  # : () -> Riffer::Catalog
+  def reload_catalog: () -> Riffer::Catalog
+
   # When not +:none+, seeded messages passed to +Riffer::Agent#generate+ must
   # carry their own +id+.
   attr_reader message_id_strategy: Symbol

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