class Riffer::Params

A DSL for defining tool parameters and structured-output schemas, used within a Tool’s params block.

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 31
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)+. Raises Riffer::ArgumentError on features outside the Params-expressible subset of JSON Schema.

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

new ()

Source

# File lib/riffer/params.rb, line 18
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 66
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 49
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 128
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 is listed in required and optional ones are made nullable instead, satisfying providers that enforce strict structured output schemas.

validate (arguments)

Source

# File lib/riffer/params.rb, line 86
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.