riffer 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 948e36451ba6cbe794054e91152030b3a5f1c89e4d81dddac69fe6624dad1a14
-  data.tar.gz: e3ec468daf389cac46ba6f5b027987f939ffc263611c27160a637b0525e84506
+  metadata.gz: 6fff2cbd2ae809651bb2a3b54cc79e591d9ba295fe8d096769e74ee75159e32b
+  data.tar.gz: 18ea73a692e864fbb2bd1c4c880ec293348cd4012a5218364b9207d51686b9bf
 SHA512:
-  metadata.gz: 060c70baee5ae31adbf8b5442be9c163c6c69931df310260005d836f9bfcddf53c17f2e705f194f37197d94345bf31449b992702bf457471262d689cbe806731
-  data.tar.gz: f10ebb1ee13561a3a197c1fb757fdc1a41dbacb04499c1160c26f116510b43fb4150b83ab17d77696713f36b896d0bbdc830f0cb0bc8266c28a5a469aab020c8
+  metadata.gz: 01eeb93e3253a1061d884e19470f880eebfdd354e3ae1a32673364533411e67f9e0ccfb48a1a90d7be88e12d0bf0d5b3027ea399e517b2d18783ec8599b0ee4b
+  data.tar.gz: fd8ca068330ab1858055dc3e5a0fc75a69db606189cfe7af5feac049e8b634919fb78e3501a8bb513bc542d1883babfe627d8b6a355927eb1df4707dc05943a6

data/.agents/providers.md

@@ -116,9 +116,19 @@ def build_request_params(messages, model, options)
 end
 ```
 
+### Strict schema
+
+All providers apply `strict_schema` (defined in `Providers::Base`) to schemas sent to LLMs — both structured output and tool parameters. This transformation:
+
+- Moves all properties into `required`
+- Makes originally-optional properties nullable (`[type, "null"]`)
+- Recurses into nested objects and array items
+
+This ensures all providers return proper `null` for optional fields instead of empty strings or garbage.
+
 ### Provider-specific formats
 
-**OpenAI** — uses `params[:text][:format]`:
+**OpenAI** — uses `params[:text][:format]` with `strict: true`:
 
 ```ruby
 if structured_output
@@ -126,7 +136,7 @@ if structured_output
     format: {
       type: "json_schema",
       name: "response",
-      schema: structured_output.json_schema,
+      schema: strict_schema(structured_output.json_schema),
       strict: true
     }
   }
@@ -140,7 +150,7 @@ if structured_output
   params[:output_config] = {
     format: {
       type: "json_schema",
-      schema: structured_output.json_schema
+      schema: strict_schema(structured_output.json_schema)
     }
   }
 end
@@ -155,7 +165,7 @@ if structured_output
       type: "json_schema",
       structure: {
         json_schema: {
-          schema: structured_output.json_schema.to_json,
+          schema: strict_schema(structured_output.json_schema).to_json,
           name: "response"
         }
       }
@@ -167,6 +177,7 @@ end
 ### Key details
 
 - `structured_output.json_schema` returns a Hash with `type`, `properties`, `required`, and `additionalProperties` keys
+- All providers wrap schemas with `strict_schema` to ensure proper null handling
 - Bedrock requires the schema as a JSON string (`.to_json`), others use the Hash directly
 - The agent handles parsing and validation of the response — providers only need to pass the schema to the SDK
 

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.15.1"
+  ".": "0.16.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.16.0](https://github.com/janeapp/riffer/compare/riffer/v0.15.1...riffer/v0.16.0) (2026-02-27)
+
+
+### Features
+
+* add Riffer::Boolean sentinel type for boolean params ([#147](https://github.com/janeapp/riffer/issues/147)) ([5337cf3](https://github.com/janeapp/riffer/commit/5337cf3820d54cf9e03a630ca32b8a7f59347221))
+* nested params DSL and strict schema for all providers ([#144](https://github.com/janeapp/riffer/issues/144)) ([2984855](https://github.com/janeapp/riffer/commit/2984855c64a1d0b421497aa81c5e0a393d443e46))
+
 ## [0.15.1](https://github.com/janeapp/riffer/compare/riffer/v0.15.0...riffer/v0.15.1) (2026-02-25)
 
 

data/README.md

@@ -93,6 +93,28 @@ Run the interactive console:
 bin/console
 ```
 
+### Recording VCR Cassettes
+
+Integration tests use [VCR](https://github.com/vcr/vcr) to record and replay HTTP interactions. When adding new tests that hit provider APIs, you need to record cassettes with real API keys.
+
+Create a `.env` file in the project root (it is gitignored):
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+AWS_BEDROCK_API_TOKEN=...
+```
+
+The test helper loads this file automatically via `dotenv`. Then run the specific tests that need new cassettes:
+
+```bash
+bundle exec ruby -Itest test/riffer/providers/open_ai_test.rb
+bundle exec ruby -Itest test/riffer/providers/anthropic_test.rb
+bundle exec ruby -Itest test/riffer/providers/amazon_bedrock_test.rb
+```
+
+VCR records the HTTP interactions to `test/fixtures/vcr_cassettes/` on the first run. Subsequent runs replay from the cassettes without hitting the API. API keys are automatically filtered from recorded cassettes.
+
 ## Contributing
 
 1. Fork the repository and create your branch: `git checkout -b feature/foo`

data/docs/01_OVERVIEW.md

@@ -39,7 +39,7 @@ See [Tools](04_TOOLS.md) for details.
 
 ### Structured Output
 
-Agents can return structured JSON responses that conform to a schema. The response is automatically parsed and validated:
+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):
 
 ```ruby
 class SentimentAgent < Riffer::Agent
@@ -47,11 +47,15 @@ class SentimentAgent < Riffer::Agent
   structured_output do
     required :sentiment, String
     required :score, Float
+    required :entities, Array, description: "Named entities" do
+      required :name, String
+      required :type, String, enum: ["person", "place", "org"]
+    end
   end
 end
 
 response = SentimentAgent.generate('Analyze: "I love this!"')
-response.structured_output  # => {sentiment: "positive", score: 0.95}
+response.structured_output  # => {sentiment: "positive", score: 0.95, entities: [...]}
 ```
 
 See the [structured output section in Agents](03_AGENTS.md#structured_output) for details.

data/docs/03_AGENTS.md

@@ -149,6 +149,74 @@ end
 
 The LLM response is automatically parsed and validated against the schema. Access the result via `response.structured_output`.
 
+#### Nested Objects
+
+Use `Hash` with a block to define nested object schemas:
+
+```ruby
+structured_output do
+  required :name, String, description: "Person name"
+  required :address, Hash, description: "Mailing address" do
+    required :street, String, description: "Street address"
+    required :city, String, description: "City"
+    optional :postal_code, String, description: "Postal or zip code"
+  end
+end
+```
+
+Validation errors use dot-path notation: `address.city is required`.
+
+#### Typed Arrays
+
+Use `Array` with the `of:` keyword for arrays of primitive types:
+
+```ruby
+structured_output do
+  required :tags, Array, of: String, description: "Tags"
+  required :scores, Array, of: Float, description: "Scores"
+end
+```
+
+Only primitive types are allowed with `of:`: `String`, `Integer`, `Float`, `TrueClass`, `FalseClass`.
+
+#### Arrays of Objects
+
+Use `Array` with a block to define arrays of objects:
+
+```ruby
+structured_output do
+  required :items, Array, description: "Line items" do
+    required :name, String, description: "Product name"
+    required :price, Float, description: "Price"
+    optional :quantity, Integer, description: "Quantity"
+  end
+end
+```
+
+Validation errors include the array index: `items[1].price is required`.
+
+#### Deep Nesting
+
+Blocks can be nested arbitrarily deep:
+
+```ruby
+structured_output do
+  required :orders, Array, description: "Orders" do
+    required :id, String, description: "Order ID"
+    required :shipping, Hash, description: "Shipping info" do
+      required :address, Hash, description: "Address" do
+        required :street, String
+        required :city, String
+      end
+    end
+  end
+end
+```
+
+#### Limitations
+
+Using both `of:` and a block raises `Riffer::ArgumentError`. Using `of:` with a non-primitive type (e.g. `of: Hash`) also raises `Riffer::ArgumentError`.
+
 Structured output is not compatible with streaming — calling `stream` on an agent with structured output configured raises `Riffer::ArgumentError`.
 
 ### guardrail

data/docs/04_TOOLS.md

@@ -104,10 +104,41 @@ Options:
 | `String`                   | `string`         |
 | `Integer`                  | `integer`        |
 | `Float`                    | `number`         |
+| `Riffer::Boolean`          | `boolean`        |
 | `TrueClass` / `FalseClass` | `boolean`        |
 | `Array`                    | `array`          |
 | `Hash`                     | `object`         |
 
+`Riffer::Boolean` is the preferred way to declare boolean parameters. `TrueClass` and `FalseClass` continue to work for backwards compatibility.
+
+### 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](03_AGENTS.md#nested-objects) for full syntax.
+
+```ruby
+class CreateOrderTool < Riffer::Tool
+  description "Creates an order"
+
+  params do
+    required :items, Array, description: "Line items" do
+      required :product_id, Integer
+      required :quantity, Integer
+      optional :notes, String
+    end
+    required :shipping, Hash, description: "Shipping address" do
+      required :street, String
+      required :city, String
+      optional :zip, String
+    end
+  end
+
+  def call(context:, items:, shipping:)
+    # items is an Array of Hashes with symbolized keys
+    # shipping is a Hash with symbolized keys
+  end
+end
+```
+
 ## The call Method
 
 Every tool must implement the `call` method and return a `Riffer::Tools::Response`:

data/lib/riffer/boolean.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Riffer::Boolean is a sentinel type for declaring boolean parameters.
+#
+# Ruby has no +Boolean+ class (+true+ is +TrueClass+, +false+ is +FalseClass+).
+# Use this module wherever you need a single type that means "boolean":
+#
+#   required :verbose, Riffer::Boolean
+#
+module Riffer::Boolean
+end

data/lib/riffer/param.rb

@@ -10,11 +10,15 @@ class Riffer::Param
     String => "string",
     Integer => "integer",
     Float => "number",
+    Riffer::Boolean => "boolean",
     TrueClass => "boolean",
     FalseClass => "boolean",
     Array => "array",
     Hash => "object"
-  }.freeze #: Hash[Class, String]
+  }.freeze #: Hash[Module, String]
+
+  # Primitive types allowed for the +of:+ keyword on Array params
+  PRIMITIVE_TYPES = (TYPE_MAPPINGS.keys - [Array, Hash]).freeze #: Array[Class]
 
   attr_reader :name #: Symbol
   attr_reader :type #: Class
@@ -22,15 +26,19 @@ class Riffer::Param
   attr_reader :description #: String?
   attr_reader :enum #: Array[untyped]?
   attr_reader :default #: untyped
+  attr_reader :item_type #: Class?
+  attr_reader :nested_params #: Riffer::Params?
 
-  #: (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped) -> void
-  def initialize(name:, type:, required:, description: nil, enum: nil, default: nil)
+  #: (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Class?, ?nested_params: Riffer::Params?) -> void
+  def initialize(name:, type:, required:, description: nil, enum: nil, default: nil, item_type: nil, nested_params: nil)
     @name = name.to_sym
     @type = type
     @required = required
     @description = description
     @enum = enum
     @default = default
+    @item_type = item_type
+    @nested_params = nested_params
   end
 
   # Validates that a value matches the expected type.
@@ -39,7 +47,7 @@ class Riffer::Param
   def valid_type?(value)
     return true if value.nil? && !required
 
-    if type == TrueClass || type == FalseClass
+    if type == Riffer::Boolean || type == TrueClass || type == FalseClass
       value == true || value == false
     else
       value.is_a?(type)
@@ -55,11 +63,27 @@ class Riffer::Param
 
   # Converts this parameter to JSON Schema format.
   #
-  #: () -> Hash[Symbol, untyped]
-  def to_json_schema
-    schema = {type: type_name}
+  # When +strict+ is true, optional parameters are made nullable
+  # (+["type", "null"]+) so that strict mode providers can distinguish
+  # "absent" from "present" without rejecting the schema.
+  #
+  #: (?strict: bool) -> Hash[Symbol, untyped]
+  def to_json_schema(strict: false)
+    type = type_name
+    type = [type, "null"] if strict && !required
+
+    schema = {type: type}
     schema[:description] = description if description
     schema[:enum] = enum if enum
+
+    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]}
+    elsif self.type == Hash && nested_params
+      schema.merge!(nested_params.to_json_schema(strict: strict))
+    end
+
     schema
   end
 end

data/lib/riffer/params.rb

@@ -21,28 +21,34 @@ class Riffer::Params
 
   # Defines a required parameter.
   #
-  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?) -> void
-  def required(name, type, description: nil, enum: nil)
+  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ () -> void } -> void
+  def required(name, type, description: nil, enum: nil, of: nil, &block)
+    nested = build_nested(type, of, &block)
     @parameters << Riffer::Param.new(
       name: name,
       type: type,
       required: true,
       description: description,
-      enum: enum
+      enum: enum,
+      item_type: of,
+      nested_params: nested
     )
   end
 
   # Defines an optional parameter.
   #
-  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped) -> void
-  def optional(name, type, description: nil, enum: nil, default: nil)
+  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ () -> void } -> void
+  def optional(name, type, description: nil, enum: nil, default: nil, of: nil, &block)
+    nested = build_nested(type, of, &block)
     @parameters << Riffer::Param.new(
       name: name,
       type: type,
       required: false,
       description: description,
       enum: enum,
-      default: default
+      default: default,
+      item_type: of,
+      nested_params: nested
     )
   end
 
@@ -78,6 +84,8 @@ class Riffer::Params
         next
       end
 
+      value = validate_nested(param, value, errors)
+
       validated[param.name] = value
     end
 
@@ -88,14 +96,18 @@ class Riffer::Params
 
   # Converts all parameters to JSON Schema format.
   #
-  #: () -> Hash[Symbol, untyped]
-  def to_json_schema
+  # When +strict+ is true, every property appears in +required+ and
+  # optional properties are made nullable instead. This satisfies
+  # providers that enforce strict structured output schemas.
+  #
+  #: (?strict: bool) -> Hash[Symbol, untyped]
+  def to_json_schema(strict: false)
     properties = {}
     required_params = []
 
     @parameters.each do |param|
-      properties[param.name.to_s] = param.to_json_schema
-      required_params << param.name.to_s if param.required
+      properties[param.name.to_s] = param.to_json_schema(strict: strict)
+      required_params << param.name.to_s if strict || param.required
     end
 
     {
@@ -105,4 +117,99 @@ class Riffer::Params
       additionalProperties: false
     }
   end
+
+  private
+
+  #: (Class, Class?) ?{ () -> void } -> Riffer::Params?
+  def build_nested(type, of, &block)
+    if of && block
+      raise Riffer::ArgumentError, "cannot use both of: and a block"
+    end
+
+    if of
+      unless type == Array
+        raise Riffer::ArgumentError, "of: can only be used with Array type, got #{type}"
+      end
+      unless Riffer::Param::PRIMITIVE_TYPES.include?(of)
+        raise Riffer::ArgumentError,
+          "of: must be a primitive type (#{Riffer::Param::PRIMITIVE_TYPES.map(&:name).join(", ")}), got #{of}"
+      end
+      return nil
+    end
+
+    if block
+      unless type == Hash || type == Array
+        raise Riffer::ArgumentError, "block can only be used with Hash or Array type, got #{type}"
+      end
+      nested = Riffer::Params.new
+      nested.instance_eval(&block)
+      nested
+    end
+  end
+
+  #: (Riffer::Param, untyped, Array[String]) -> untyped
+  def validate_nested(param, value, errors)
+    if 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)
+    elsif param.type == Array && param.item_type
+      validate_typed_array(param, value, errors)
+      value
+    else
+      value
+    end
+  end
+
+  #: (Riffer::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+  def validate_nested_hash(param, value, errors)
+    sym_value = deep_symbolize_keys(value)
+    param.nested_params.validate(sym_value)
+  rescue Riffer::ValidationError => e
+    e.message.split("; ").each do |msg|
+      errors << "#{param.name}.#{msg}"
+    end
+    sym_value
+  end
+
+  #: (Riffer::Param, Array[untyped], Array[String]) -> Array[untyped]
+  def validate_nested_array_of_objects(param, value, errors)
+    value.map.with_index do |item, i|
+      unless item.is_a?(Hash)
+        errors << "#{param.name}[#{i}] must be an object"
+        next item
+      end
+      sym_item = deep_symbolize_keys(item)
+      param.nested_params.validate(sym_item)
+    rescue Riffer::ValidationError => e
+      e.message.split("; ").each do |msg|
+        errors << "#{param.name}[#{i}].#{msg}"
+      end
+      sym_item
+    end
+  end
+
+  #: (Riffer::Param, Array[untyped], Array[String]) -> void
+  def validate_typed_array(param, value, errors)
+    type_name = Riffer::Param::TYPE_MAPPINGS[param.item_type]
+    value.each_with_index do |item, i|
+      valid = if param.item_type == Riffer::Boolean || param.item_type == TrueClass || param.item_type == FalseClass
+        item == true || item == false
+      else
+        item.is_a?(param.item_type)
+      end
+      errors << "#{param.name}[#{i}] must be a #{type_name}" unless valid
+    end
+  end
+
+  #: (Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+  def deep_symbolize_keys(hash)
+    hash.each_with_object({}) do |(key, value), result|
+      result[key.to_sym] = case value
+      when Hash then deep_symbolize_keys(value)
+      when Array then value.map { |v| v.is_a?(Hash) ? deep_symbolize_keys(v) : v }
+      else value
+      end
+    end
+  end
 end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -50,12 +50,15 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     end
 
     if structured_output
+      # Use strict schema to make optional fields nullable. Without this,
+      # Bedrock may return string literals like ": null," instead of actual
+      # null values for optional fields that the model has no value for.
       params[:output_config] = {
         text_format: {
           type: "json_schema",
           structure: {
             json_schema: {
-              schema: structured_output.json_schema.to_json,
+              schema: structured_output.json_schema(strict: true).to_json,
               name: "response"
             }
           }
@@ -302,7 +305,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
         name: tool.name,
         description: tool.description,
         input_schema: {
-          json: tool.parameters_schema
+          json: tool.parameters_schema(strict: true)
         }
       }
     }

data/lib/riffer/providers/anthropic.rb

@@ -50,10 +50,13 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     end
 
     if structured_output
+      # Use strict schema to make optional fields nullable. Without this,
+      # Anthropic may return empty strings or whitespace instead of null
+      # for optional fields that the model has no value for.
       params[:output_config] = {
         format: {
           type: "json_schema",
-          schema: structured_output.json_schema
+          schema: structured_output.json_schema(strict: true)
         }
       }
     end
@@ -335,7 +338,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     {
       name: tool.name,
       description: tool.description,
-      input_schema: tool.parameters_schema
+      input_schema: tool.parameters_schema(strict: true)
     }
   end
 end

data/lib/riffer/providers/open_ai.rb

@@ -46,11 +46,13 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     end
 
     if structured_output
+      # OpenAI requires strict mode schemas.
+      # https://platform.openai.com/docs/guides/structured-outputs#all-fields-must-be-required
       params[:text] = {
         format: {
           type: "json_schema",
           name: "response",
-          schema: structured_output.json_schema,
+          schema: structured_output.json_schema(strict: true),
           strict: true
         }
       }
@@ -292,7 +294,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       type: "function",
       name: tool.name,
       description: tool.description,
-      parameters: tool.parameters_schema,
+      parameters: tool.parameters_schema(strict: true),
       strict: true
     }
   end

data/lib/riffer/structured_output.rb

@@ -14,12 +14,17 @@ require "json"
 #
 class Riffer::StructuredOutput
   attr_reader :params #: Riffer::Params
-  attr_reader :json_schema #: Hash[Symbol, untyped]
 
   #: (Riffer::Params) -> void
   def initialize(params)
     @params = params
-    @json_schema = @params.to_json_schema
+  end
+
+  # Returns the JSON Schema for this structured output.
+  #
+  #: (?strict: bool) -> Hash[Symbol, untyped]
+  def json_schema(strict: false)
+    @params.to_json_schema(strict: strict)
   end
 
   # Parses a JSON string and validates it against the schema.

data/lib/riffer/tool.rb

@@ -74,9 +74,9 @@ class Riffer::Tool
 
   # Returns the JSON Schema for the tool's parameters.
   #
-  #: () -> Hash[Symbol, untyped]
-  def self.parameters_schema
-    @params_builder&.to_json_schema || empty_schema
+  #: (?strict: bool) -> Hash[Symbol, untyped]
+  def self.parameters_schema(strict: false)
+    @params_builder&.to_json_schema(strict: strict) || empty_schema
   end
 
   def self.empty_schema # :nodoc:

data/lib/riffer/version.rb

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

data/sig/generated/riffer/boolean.rbs

@@ -0,0 +1,10 @@
+# Generated from lib/riffer/boolean.rb with RBS::Inline
+
+# Riffer::Boolean is a sentinel type for declaring boolean parameters.
+#
+# Ruby has no +Boolean+ class (+true+ is +TrueClass+, +false+ is +FalseClass+).
+# Use this module wherever you need a single type that means "boolean":
+#
+#   required :verbose, Riffer::Boolean
+module Riffer::Boolean
+end

data/sig/generated/riffer/param.rbs

@@ -5,7 +5,10 @@
 # Handles type validation and JSON Schema generation for individual parameters.
 class Riffer::Param
   # Maps Ruby types to JSON Schema type strings
-  TYPE_MAPPINGS: Hash[Class, String]
+  TYPE_MAPPINGS: Hash[Module, String]
+
+  # Primitive types allowed for the +of:+ keyword on Array params
+  PRIMITIVE_TYPES: Array[Class]
 
   attr_reader name: Symbol
 
@@ -19,8 +22,12 @@ class Riffer::Param
 
   attr_reader default: untyped
 
-  # : (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped) -> void
-  def initialize: (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped) -> void
+  attr_reader item_type: Class?
+
+  attr_reader nested_params: Riffer::Params?
+
+  # : (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Class?, ?nested_params: Riffer::Params?) -> void
+  def initialize: (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Class?, ?nested_params: Riffer::Params?) -> void
 
   # Validates that a value matches the expected type.
   #
@@ -34,6 +41,10 @@ class Riffer::Param
 
   # Converts this parameter to JSON Schema format.
   #
-  # : () -> Hash[Symbol, untyped]
-  def to_json_schema: () -> Hash[Symbol, untyped]
+  # When +strict+ is true, optional parameters are made nullable
+  # (+["type", "null"]+) so that strict mode providers can distinguish
+  # "absent" from "present" without rejecting the schema.
+  #
+  # : (?strict: bool) -> Hash[Symbol, untyped]
+  def to_json_schema: (?strict: bool) -> Hash[Symbol, untyped]
 end

data/sig/generated/riffer/params.rbs

@@ -17,13 +17,13 @@ class Riffer::Params
 
   # Defines a required parameter.
   #
-  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?) -> void
-  def required: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?) -> void
+  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ () -> void } -> void
+  def required: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ () -> void } -> void
 
   # Defines an optional parameter.
   #
-  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped) -> void
-  def optional: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped) -> void
+  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ () -> void } -> void
+  def optional: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ () -> void } -> void
 
   # Validates arguments against parameter definitions.
   #
@@ -34,6 +34,30 @@ class Riffer::Params
 
   # Converts all parameters to JSON Schema format.
   #
-  # : () -> Hash[Symbol, untyped]
-  def to_json_schema: () -> Hash[Symbol, untyped]
+  # When +strict+ is true, every property appears in +required+ and
+  # optional properties are made nullable instead. This satisfies
+  # providers that enforce strict structured output schemas.
+  #
+  # : (?strict: bool) -> Hash[Symbol, untyped]
+  def to_json_schema: (?strict: bool) -> Hash[Symbol, untyped]
+
+  private
+
+  # : (Class, Class?) ?{ () -> void } -> Riffer::Params?
+  def build_nested: (Class, Class?) ?{ () -> void } -> Riffer::Params?
+
+  # : (Riffer::Param, untyped, Array[String]) -> untyped
+  def validate_nested: (Riffer::Param, untyped, Array[String]) -> untyped
+
+  # : (Riffer::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+  def validate_nested_hash: (Riffer::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+
+  # : (Riffer::Param, Array[untyped], Array[String]) -> Array[untyped]
+  def validate_nested_array_of_objects: (Riffer::Param, Array[untyped], Array[String]) -> Array[untyped]
+
+  # : (Riffer::Param, Array[untyped], Array[String]) -> void
+  def validate_typed_array: (Riffer::Param, Array[untyped], Array[String]) -> void
+
+  # : (Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+  def deep_symbolize_keys: (Hash[untyped, untyped]) -> Hash[Symbol, untyped]
 end

data/sig/generated/riffer/structured_output.rbs

@@ -11,11 +11,14 @@
 class Riffer::StructuredOutput
   attr_reader params: Riffer::Params
 
-  attr_reader json_schema: Hash[Symbol, untyped]
-
   # : (Riffer::Params) -> void
   def initialize: (Riffer::Params) -> void
 
+  # Returns the JSON Schema for this structured output.
+  #
+  # : (?strict: bool) -> Hash[Symbol, untyped]
+  def json_schema: (?strict: bool) -> Hash[Symbol, untyped]
+
   # Parses a JSON string and validates it against the schema.
   #
   # Returns a Result with the validated object on success, or an error message on failure.

data/sig/generated/riffer/tool.rbs

@@ -54,8 +54,8 @@ class Riffer::Tool
 
   # Returns the JSON Schema for the tool's parameters.
   #
-  # : () -> Hash[Symbol, untyped]
-  def self.parameters_schema: () -> Hash[Symbol, untyped]
+  # : (?strict: bool) -> Hash[Symbol, untyped]
+  def self.parameters_schema: (?strict: bool) -> Hash[Symbol, untyped]
 
   def self.empty_schema: () -> untyped
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -218,6 +218,7 @@ files:
 - lib/riffer.rb
 - lib/riffer/agent.rb
 - lib/riffer/agent/response.rb
+- lib/riffer/boolean.rb
 - lib/riffer/config.rb
 - lib/riffer/core.rb
 - lib/riffer/evals.rb
@@ -278,6 +279,7 @@ files:
 - sig/generated/riffer.rbs
 - sig/generated/riffer/agent.rbs
 - sig/generated/riffer/agent/response.rbs
+- sig/generated/riffer/boolean.rbs
 - sig/generated/riffer/config.rbs
 - sig/generated/riffer/core.rbs
 - sig/generated/riffer/evals.rbs