class Riffer::Params

Riffer::Params provides a DSL for defining parameters.

Used within a Tool’s params block to define required and optional parameters, and by StructuredOutput to define response schemas.

params do
  required :city, String, description: "The city name"
  optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
end

Public Class Methods

from_json_schema (schema)

Source

# File lib/riffer/params.rb, line 40
def self.from_json_schema(schema)
  params = new
  properties = schema[:properties] || {}
  required = (schema[:required] || []).map { |key| key.to_s }

  properties.each do |name, property_schema|
    params.parameters << Riffer::Params::Param.from_json_schema(
      name.to_sym, property_schema, required: required.include?(name.to_s)
    )
  end

  params
end

Reconstructs a Params from a JSON Schema object (the inverse of +to_json_schema(strict: false)+).

Accepts the Symbol-keyed object schema produced by to_json_schema (property-name keys may be String or Symbol — both are normalized). Reconstructs types, required, description, enum, default, typed-array item_type, and nested object/array Params recursively.

Round-trips losslessly with +to_json_schema(strict: false)+ over the Params-expressible subset of JSON Schema. Raises Riffer::ArgumentError on a schema using features outside that subset.

schema = params.to_json_schema(strict: false)
Riffer::Params.from_json_schema(schema) # => equivalent Riffer::Params

new ()

Source

# File lib/riffer/params.rb, line 19
def initialize
  @parameters = []
end

Public Instance Methods

optional (name, type, description: nil, enum: nil, default: nil, of: nil, &block)

Source

# File lib/riffer/params.rb, line 75
def optional(name, type, description: nil, enum: nil, default: nil, of: nil, &block)
  nested = build_nested(type, of, &block)
  @parameters << Riffer::Params::Param.new(
    name: name,
    type: type,
    required: false,
    description: description,
    enum: enum,
    default: default,
    item_type: of,
    nested_params: nested
  )
end

Defines an optional parameter.

required (name, type, description: nil, enum: nil, of: nil, &block)

Source

# File lib/riffer/params.rb, line 58
def required(name, type, description: nil, enum: nil, of: nil, &block)
  nested = build_nested(type, of, &block)
  @parameters << Riffer::Params::Param.new(
    name: name,
    type: type,
    required: true,
    description: description,
    enum: enum,
    item_type: of,
    nested_params: nested
  )
end

Defines a required parameter.

to_json_schema (strict: false)

Source

# File lib/riffer/params.rb, line 140
def to_json_schema(strict: false)
  properties = {} #: Hash[String, untyped]
  required_params = [] #: Array[String]

  @parameters.each do |param|
    properties[param.name.to_s] = param.to_json_schema(strict: strict)
    required_params << param.name.to_s if strict || param.required
  end

  {
    type: "object",
    properties: properties,
    required: required_params,
    additionalProperties: false
  }
end

Converts all parameters to JSON Schema format.

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.

validate (arguments)

Source

# File lib/riffer/params.rb, line 95
def validate(arguments)
  validated = {} #: Hash[Symbol, untyped]
  errors = [] #: Array[String]

  @parameters.each do |param|
    value = arguments[param.name]

    if value.nil? && param.required
      errors << "#{param.name} is required"
      next
    end

    if value.nil?
      validated[param.name] = param.default
      next
    end

    unless param.valid_type?(value)
      errors << "#{param.name} must be a #{param.type_name}"
      next
    end

    if param.enum && !param.enum.include?(value)
      errors << "#{param.name} must be one of: #{param.enum.join(", ")}"
      next
    end

    value = validate_nested(param, value, errors)

    validated[param.name] = value
  end

  raise Riffer::ValidationError, errors.join("; ") if errors.any?

  validated
end

Validates arguments against parameter definitions.

Raises Riffer::ValidationError if validation fails.