Class: Riffer::Params

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

Overview

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

Defined Under Namespace

Modules: Boolean Classes: Param

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Params

– : () -> void



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

def initialize
  @parameters = []
end

Instance Attribute Details

#parameters ⇒ Object (readonly)

The defined parameters.



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

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). 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

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



31
32
33
34
35
36
37
38
39
40
41
42
43
 
# 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

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



66
67
68
69
70
71
72
73
74
75
76
77
78
 
# 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

#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



49
50
51
52
53
54
55
56
57
58
59
60
 
# 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

#to_json_schema(strict: false) ⇒ Object

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. – : (?strict: bool) -> Hash[Symbol, untyped]



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# 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

#validate(arguments) ⇒ Object

Validates arguments against parameter definitions.

Raises Riffer::ValidationError if validation fails.

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

Raises:



86
87
88
89
90
91
92
93
94
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
 
# 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