Class: Riffer::Params

Inherits:
Object
  • Object
show all
Defined in:
lib/riffer/params.rb

Overview

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

Defined Under Namespace

Modules: Boolean Classes: Param

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Params

– : () -> void



19
20
21
 
# File 'lib/riffer/params.rb', line 19

def initialize
  @parameters = []
end

Instance Attribute Details

#parameters ⇒ Object (readonly)

: Array



15
16
17
 
# File 'lib/riffer/params.rb', line 15

def parameters
  @parameters
end

Class Method Details

.from_json_schema(schema) ⇒ Object

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

– : (Hash[Symbol, untyped]) -> Riffer::Params



40
41
42
43
44
45
46
47
48
49
50
51
52
 
# 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

Instance Method Details

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

Defines an optional parameter.

– : (Symbol, Module, ?description: String?, ?enum: Array?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void



75
76
77
78
79
80
81
82
83
84
85
86
87
 
# 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

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

Defines a required parameter.

– : (Symbol, Module, ?description: String?, ?enum: Array?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void



58
59
60
61
62
63
64
65
66
67
68
69
 
# 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

#to_json_schema(strict: false) ⇒ Object

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.

– : (?strict: bool) -> Hash[Symbol, untyped]



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# 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

#validate(arguments) ⇒ Object

Validates arguments against parameter definitions.

Raises Riffer::ValidationError if validation fails.

– : (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]

Raises:



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# 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