riffer 0.53.0 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/rules/rbs-inline.md +8 -8
  3. data/.release-please-manifest.json +1 -1
  4. data/.ruby-version +1 -1
  5. data/CHANGELOG.md +43 -0
  6. data/README.md +24 -0
  7. data/Steepfile +19 -0
  8. data/docs/AGENTS.md +101 -14
  9. data/docs/CATALOG.md +8 -8
  10. data/docs/CONFIGURATION.md +47 -16
  11. data/docs/MCP.md +3 -4
  12. data/docs/OVERVIEW.md +1 -1
  13. data/docs/STREAM_EVENTS.md +1 -1
  14. data/docs/TOOLS.md +15 -12
  15. data/docs/TRACING.md +1 -1
  16. data/docs/providers/AMAZON_BEDROCK.md +2 -0
  17. data/docs/providers/ANTHROPIC.md +32 -36
  18. data/docs/providers/CUSTOM_PROVIDERS.md +35 -0
  19. data/docs/providers/GEMINI.md +76 -25
  20. data/docs/providers/GOOGLE_CLOUD.md +363 -0
  21. data/docs/providers/PROVIDERS.md +30 -18
  22. data/docs-site/manifest.yml +3 -0
  23. data/lib/riffer/agent/structured_output.rb +28 -3
  24. data/lib/riffer/config/anthropic.rb +9 -0
  25. data/lib/riffer/config/gemini.rb +9 -0
  26. data/lib/riffer/config/google_cloud.rb +38 -0
  27. data/lib/riffer/config.rb +3 -0
  28. data/lib/riffer/http/client.rb +141 -0
  29. data/lib/riffer/http.rb +5 -0
  30. data/lib/riffer/mcp/client.rb +0 -1
  31. data/lib/riffer/params/any_of.rb +50 -0
  32. data/lib/riffer/params/format.rb +73 -0
  33. data/lib/riffer/params/param.rb +143 -19
  34. data/lib/riffer/params.rb +156 -30
  35. data/lib/riffer/providers/amazon_bedrock.rb +38 -5
  36. data/lib/riffer/providers/anthropic/client.rb +49 -0
  37. data/lib/riffer/providers/anthropic.rb +19 -452
  38. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +195 -0
  39. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +293 -0
  40. data/lib/riffer/providers/anthropic_compatible.rb +5 -0
  41. data/lib/riffer/providers/anthropic_vertex.rb +66 -0
  42. data/lib/riffer/providers/base.rb +13 -16
  43. data/lib/riffer/providers/gemini/client.rb +17 -85
  44. data/lib/riffer/providers/gemini.rb +213 -80
  45. data/lib/riffer/providers/google_cloud/client.rb +106 -0
  46. data/lib/riffer/providers/google_cloud.rb +99 -0
  47. data/lib/riffer/providers/repository.rb +2 -0
  48. data/lib/riffer/version.rb +1 -1
  49. data/lib/riffer/wire/sse.rb +51 -0
  50. data/lib/riffer/wire.rb +31 -0
  51. data/lib/riffer.rb +18 -0
  52. data/rbs_collection.lock.yaml +32 -4
  53. data/rbs_collection.yaml +2 -0
  54. data/sig/_private/faraday.rbs +8 -0
  55. data/sig/_private/googleauth.rbs +7 -0
  56. data/sig/generated/riffer/agent/structured_output.rbs +6 -0
  57. data/sig/generated/riffer/config/anthropic.rbs +6 -0
  58. data/sig/generated/riffer/config/gemini.rbs +6 -0
  59. data/sig/generated/riffer/config/google_cloud.rbs +28 -0
  60. data/sig/generated/riffer/config.rbs +2 -0
  61. data/sig/generated/riffer/http/client.rbs +59 -0
  62. data/sig/generated/riffer/http.rbs +4 -0
  63. data/sig/generated/riffer/params/any_of.rbs +21 -0
  64. data/sig/generated/riffer/params/format.rbs +39 -0
  65. data/sig/generated/riffer/params/param.rbs +27 -4
  66. data/sig/generated/riffer/params.rbs +38 -8
  67. data/sig/generated/riffer/providers/amazon_bedrock.rbs +14 -2
  68. data/sig/generated/riffer/providers/anthropic/client.rbs +34 -0
  69. data/sig/generated/riffer/providers/anthropic.rbs +5 -124
  70. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +71 -0
  71. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +99 -0
  72. data/sig/generated/riffer/providers/anthropic_compatible.rbs +4 -0
  73. data/sig/generated/riffer/providers/anthropic_vertex.rbs +45 -0
  74. data/sig/generated/riffer/providers/gemini/client.rbs +11 -34
  75. data/sig/generated/riffer/providers/gemini.rbs +66 -4
  76. data/sig/generated/riffer/providers/google_cloud/client.rbs +71 -0
  77. data/sig/generated/riffer/providers/google_cloud.rbs +64 -0
  78. data/sig/generated/riffer/wire/sse.rbs +23 -0
  79. data/sig/generated/riffer/wire.rbs +17 -0
  80. data/sig/generated/riffer.rbs +12 -0
  81. data/sig/manifest.yaml +2 -1
  82. data/sig/manual/riffer/params/format.rbs +5 -0
  83. data/sig/manual/riffer/providers/anthropic_compatible/messages_api.rbs +8 -0
  84. data/sig/manual/riffer/providers/gemini.rbs +8 -0
  85. data/sig/manual/riffer/providers/google_cloud.rbs +8 -0
  86. data/sig/manual/riffer/wire.rbs +5 -0
  87. metadata +66 -5
  88. data/sig/_private/anthropic.rbs +0 -17
  89. data/sig/_private/riffer/providers/anthropic.rbs +0 -6
  90. data/sig/_private/riffer/providers/gemini.rbs +0 -7
@@ -0,0 +1,141 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ require "faraday"
5
+ require "json"
6
+
7
+ class Riffer::HTTP::Client
8
+ # @rbs @connection: Faraday::Connection
9
+ # @rbs @extra_headers: Hash[String, String]
10
+
11
+ DEFAULT_OPEN_TIMEOUT = 10 #: Integer
12
+ DEFAULT_READ_TIMEOUT = 600 #: Integer
13
+
14
+ # +headers+ are sent on every request and win over the subclass's auth and
15
+ # version headers, as do headers set on the +connection+.
16
+ #--
17
+ #: (?headers: Hash[String, String], ?connection: Faraday::Connection?) -> void
18
+ def initialize(headers: {}, connection: nil)
19
+ @extra_headers = headers
20
+ @connection = connection || Faraday.new(
21
+ request: { open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT },
22
+ )
23
+ end
24
+
25
+ # Raises Riffer::APIError on a non-success status.
26
+ #--
27
+ #: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
28
+ def post(path, body)
29
+ response = request(path, body)
30
+ raise_api_error!(response.status, response.body) unless response.success?
31
+ JSON.parse(response.body, symbolize_names: true)
32
+ end
33
+
34
+ # Raises Riffer::APIError on a non-success status; the error body is never yielded.
35
+ #--
36
+ #: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
37
+ def post_stream(path, body, &)
38
+ streamed = false
39
+ yielded = false
40
+ held = +""
41
+
42
+ # A proc, not a lambda: httpx and typhoeus pass no env. Without one the
43
+ # status is unknown until the response returns, so every chunk is held.
44
+ on_data = proc do |chunk, bytes_received, env|
45
+ streamed = true
46
+ # Faraday restarts bytes_received on each attempt. httpx passes the chunk
47
+ # size instead, so attempts are only told apart when there is an env.
48
+ if env && bytes_received == chunk.bytesize
49
+ if yielded
50
+ raise Riffer::Error, "the stream restarted after data was delivered; " \
51
+ "retry middleware must not retry streaming requests mid-body"
52
+ end
53
+ held.clear
54
+ end
55
+
56
+ if env&.success?
57
+ unless chunk.empty?
58
+ yielded = true
59
+ yield(chunk)
60
+ end
61
+ else
62
+ held << chunk
63
+ end
64
+ end
65
+
66
+ response = request(path, body, on_data: on_data)
67
+ unyielded = streamed ? held : response.body
68
+ raise_api_error!(response.status, unyielded) unless response.success?
69
+ yield(unyielded) unless unyielded.empty?
70
+ end
71
+
72
+ private
73
+
74
+ #--
75
+ #: (String) -> String
76
+ def url_for(path)
77
+ raise NotImplementedError, "Subclasses must implement #url_for"
78
+ end
79
+
80
+ # Called per request so short-lived credentials can refresh.
81
+ #--
82
+ #: () -> Hash[String, String]
83
+ def headers
84
+ raise NotImplementedError, "Subclasses must implement #headers"
85
+ end
86
+
87
+ #--
88
+ #: () -> String
89
+ def error_label
90
+ raise NotImplementedError, "Subclasses must implement #error_label"
91
+ end
92
+
93
+ #--
94
+ #: (Hash[Symbol, untyped], String) -> String
95
+ def error_message(parsed, raw)
96
+ error = parsed[:error]
97
+ case error
98
+ when Hash then error[:message] || parsed[:message] || raw
99
+ when String then error
100
+ else parsed[:message] || raw
101
+ end
102
+ end
103
+
104
+ # Headers go on the request, never on the connection, which may be shared
105
+ # across fibers and keeps whatever headers the caller configured on it.
106
+ # Faraday matches header names case-insensitively, so a caller's header
107
+ # replaces the subclass's whatever its casing. The content and encoding
108
+ # headers below are always riffer's: the body and the stream depend on them.
109
+ #--
110
+ #: (String, Hash[Symbol, untyped], ?on_data: Proc?) -> Faraday::Response
111
+ def request(path, body, on_data: nil)
112
+ @connection.post(url_for(path)) do |req|
113
+ req.headers.update(@extra_headers)
114
+ headers.each { |name, value| req.headers[name] ||= value }
115
+ req.headers["content-type"] = "application/json"
116
+ if on_data
117
+ req.headers["accept"] = "text/event-stream"
118
+ # Net::HTTP buffers a gzip body until EOF, which stalls the stream.
119
+ req.headers["accept-encoding"] = "identity"
120
+ req.options.on_data = on_data
121
+ end
122
+ req.body = body.to_json
123
+ end
124
+ end
125
+
126
+ #--
127
+ #: (Integer, String) -> bot
128
+ def raise_api_error!(status, raw)
129
+ parsed = begin
130
+ JSON.parse(raw, symbolize_names: true)
131
+ rescue JSON::ParserError
132
+ nil
133
+ end
134
+ # Vertex AI wraps its error object in a one-element array.
135
+ parsed = parsed.first if parsed.is_a?(Array) && parsed.length == 1
136
+ fields = parsed.is_a?(Hash) ? parsed : {} #: Hash[Symbol, untyped]
137
+
138
+ message = "#{error_label} API error (#{status}): #{error_message(fields, raw)}"
139
+ raise Riffer::APIError.new(message, status: status, body: raw)
140
+ end
141
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Riffer::HTTP
5
+ end
@@ -8,7 +8,6 @@ class Riffer::Mcp::Client
8
8
  #: (endpoint: String, ?headers: (Hash[String, String] | Proc), ?client: untyped?) -> void
9
9
  def initialize(endpoint:, headers: {}, client: nil)
10
10
  depends_on "mcp"
11
- depends_on "faraday"
12
11
 
13
12
  @client = client || begin
14
13
  resolved_headers = Riffer::Helpers::CallOrValue.resolve(headers)
@@ -0,0 +1,50 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Params::AnyOf
5
+ # @rbs @name: Symbol
6
+
7
+ attr_reader :variants #: Array[Riffer::Params | Riffer::Params::Param] # @dynamic variants
8
+
9
+ #--
10
+ #: (Symbol) -> void
11
+ def initialize(name)
12
+ @name = name
13
+ @variants = []
14
+ end
15
+
16
+ #--
17
+ #: (?Module?, ?description: String?, ?enum: Array[untyped]?, ?format: String?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
18
+ def variant(type = nil, description: nil, enum: nil, format: nil, &block)
19
+ if type
20
+ raise Riffer::ArgumentError, "variant takes a type or a block, not both" if block
21
+
22
+ @variants << primitive(type, description, enum, format)
23
+ elsif block
24
+ if description || enum || format
25
+ raise Riffer::ArgumentError, "description:, enum: and format: only apply to a primitive variant"
26
+ end
27
+
28
+ params = Riffer::Params.new
29
+ params.instance_eval(&block)
30
+ @variants << params
31
+ else
32
+ raise Riffer::ArgumentError, "variant requires a type or a block defining its properties"
33
+ end
34
+ end
35
+
36
+ private
37
+
38
+ #--
39
+ #: (Module, String?, Array[untyped]?, String?) -> Riffer::Params::Param
40
+ def primitive(type, description, enum, format)
41
+ unless Riffer::Params::Param::PRIMITIVE_TYPES.include?(type)
42
+ primitives = Riffer::Params::Param::PRIMITIVE_TYPES.map(&:name).join(", ")
43
+ raise Riffer::ArgumentError, "variant type must be a primitive type (#{primitives}), got #{type}"
44
+ end
45
+
46
+ Riffer::Params::Param.new(
47
+ name: @name, type: type, required: true, description: description, enum: enum, format: format,
48
+ )
49
+ end
50
+ end
@@ -0,0 +1,73 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ require "date"
5
+ require "ipaddr"
6
+
7
+ module Riffer::Params::Format
8
+ extend self
9
+
10
+ DATE = /\A(\d{4})-(\d{2})-(\d{2})\z/ #: Regexp
11
+
12
+ DATE_TIME = /\A(\d{4})-(\d{2})-(\d{2})[Tt]([01]\d|2[0-3]):[0-5]\d:([0-5]\d|60)(\.\d+)?([Zz]|[+-]([01]\d|2[0-3]):[0-5]\d)\z/ #: Regexp
13
+
14
+ # The offset is optional: Anthropic's grammar emits times without one.
15
+ TIME = /\A([01]\d|2[0-3]):[0-5]\d:([0-5]\d|60)(\.\d+)?([Zz]|[+-]([01]\d|2[0-3]):[0-5]\d)?\z/ #: Regexp
16
+
17
+ DURATION = /\AP(?!\z)((\d+Y)?(\d+M)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?|\d+W)\z/ #: Regexp
18
+
19
+ UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/ #: Regexp
20
+
21
+ # The WHATWG HTML pattern: no single pattern matches RFC 5322 exactly, so
22
+ # this one only rules out values that are clearly not an address.
23
+ EMAIL = %r{\A[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*\z} #: Regexp
24
+
25
+ HOSTNAME = /\A(?=.{1,253}\.?\z)[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*\.?\z/ #: Regexp
26
+
27
+ # The formats OpenAI, Anthropic and Bedrock all accept. OpenAI rejects uri.
28
+ CHECKS = {
29
+ "date-time" => ->(value) { calendar_date?(DATE_TIME, value) },
30
+ "time" => ->(value) { TIME.match?(value) },
31
+ "date" => ->(value) { calendar_date?(DATE, value) },
32
+ "duration" => ->(value) { DURATION.match?(value) },
33
+ "email" => ->(value) { EMAIL.match?(value) },
34
+ "hostname" => ->(value) { HOSTNAME.match?(value) },
35
+ "ipv4" => ->(value) { ip_address?(value, &:ipv4?) },
36
+ "ipv6" => ->(value) { ip_address?(value, &:ipv6?) },
37
+ "uuid" => ->(value) { UUID.match?(value) },
38
+ }.freeze #: Hash[String, ^(String) -> bool]
39
+
40
+ private_constant :DATE, :DATE_TIME, :TIME, :DURATION, :UUID, :EMAIL, :HOSTNAME, :CHECKS
41
+
42
+ NAMES = CHECKS.keys.freeze #: Array[String]
43
+
44
+ #--
45
+ #: (String, String) -> bool
46
+ def valid?(format, value)
47
+ CHECKS.fetch(format).call(value)
48
+ end
49
+
50
+ private
51
+
52
+ #--
53
+ #: (Regexp, String) -> bool
54
+ def calendar_date?(pattern, value)
55
+ match = pattern.match(value)
56
+ return false unless match
57
+
58
+ # RFC 3339 dates are proleptic Gregorian; Date defaults to the Julian calendar before 1582.
59
+ Date.valid_date?(match[1].to_i, match[2].to_i, match[3].to_i, Date::GREGORIAN)
60
+ end
61
+
62
+ #--
63
+ #: (String) { (IPAddr) -> bool } -> bool
64
+ def ip_address?(value)
65
+ # IPAddr also accepts a prefix (10.0.0.0/24), a zone ID (fe80::1%eth0) and
66
+ # brackets ([::1]), none of which are part of an address.
67
+ return false if value.match?(%r{[/%\[\]]})
68
+
69
+ yield IPAddr.new(value)
70
+ rescue IPAddr::Error
71
+ false
72
+ end
73
+ end
@@ -1,6 +1,8 @@
1
1
  # frozen_string_literal: true
2
2
  # rbs_inline: enabled
3
3
 
4
+ require "json"
5
+
4
6
  class Riffer::Params::Param
5
7
  TYPE_MAPPINGS = {
6
8
  String => "string",
@@ -34,63 +36,136 @@ class Riffer::Params::Param
34
36
 
35
37
  attr_reader :enum #: Array[untyped]? # @dynamic enum
36
38
 
39
+ attr_reader :format #: String? # @dynamic format
40
+
37
41
  attr_reader :default #: untyped # @dynamic default
38
42
 
39
43
  attr_reader :item_type #: Module? # @dynamic item_type
40
44
 
45
+ attr_reader :dimensions #: Integer # @dynamic dimensions
46
+
41
47
  attr_reader :nested_params #: Riffer::Params? # @dynamic nested_params
42
48
 
49
+ attr_reader :variants #: Array[Riffer::Params | Riffer::Params::Param]? # @dynamic variants
50
+
43
51
  #--
44
52
  #: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
45
53
  def self.from_json_schema(name, schema, required:)
46
- ruby_type = json_type_to_ruby(schema[:type])
47
- item_type, nested = resolve_nesting(ruby_type, schema)
54
+ variants = resolve_variants(name, schema[:anyOf]) if schema.key?(:anyOf)
55
+ ruby_type = variants ? Riffer::Params::AnyOf : json_type_to_ruby(schema[:type])
56
+ nested = resolve_nested_params(ruby_type, schema)
57
+ item_type, dimensions, items = resolve_typed_items(schema) if ruby_type == Array && !nested
48
58
 
49
59
  new(
50
60
  name: name,
51
61
  type: ruby_type,
52
62
  required: required,
53
63
  description: schema[:description],
54
- enum: schema[:enum],
64
+ enum: schema[:enum] || items&.dig(:enum),
65
+ format: schema[:format] || items&.dig(:format),
55
66
  default: schema[:default],
56
67
  item_type: item_type,
68
+ dimensions: dimensions || 1,
57
69
  nested_params: nested,
70
+ variants: variants,
58
71
  )
59
72
  end
60
73
 
61
74
  #--
62
- #: (Module, Hash[Symbol, untyped]) -> [Module?, Riffer::Params?]
63
- def self.resolve_nesting(ruby_type, schema)
64
- return [nil, Riffer::Params.from_json_schema(schema)] if ruby_type == Hash && schema[:properties]
65
- return [nil, nil] unless ruby_type == Array
75
+ #: (Symbol, Array[Hash[Symbol, untyped]]) -> Array[Riffer::Params | Riffer::Params::Param]
76
+ def self.resolve_variants(name, branches)
77
+ # Strict schemas add a null branch to optional fields; nullability comes from +required+.
78
+ variants = branches.reject { |branch| branch[:type] == "null" }.map do |branch|
79
+ if branch[:type] == "object"
80
+ Riffer::Params.from_json_schema(branch)
81
+ elsif PRIMITIVE_TYPES.include?(JSON_TYPE_MAPPINGS[branch[:type]]) && !branch.key?(:anyOf)
82
+ from_json_schema(name, branch, required: true)
83
+ else
84
+ raise Riffer::ArgumentError, "Unsupported anyOf branch: #{branch.to_json}"
85
+ end
86
+ end
87
+ raise Riffer::ArgumentError, "anyOf requires at least two branches" if variants.size < 2
66
88
 
89
+ variants
90
+ end
91
+ private_class_method :resolve_variants
92
+
93
+ #--
94
+ #: (Module, Hash[Symbol, untyped]) -> Riffer::Params?
95
+ def self.resolve_nested_params(ruby_type, schema)
96
+ if ruby_type == Hash && schema[:properties]
97
+ Riffer::Params.from_json_schema(schema)
98
+ elsif ruby_type == Array && schema[:items].is_a?(Hash) && schema[:items][:properties]
99
+ Riffer::Params.from_json_schema(schema[:items])
100
+ end
101
+ end
102
+ private_class_method :resolve_nested_params
103
+
104
+ #--
105
+ #: (Hash[Symbol, untyped]) -> [Module, Integer, Hash[Symbol, untyped]]?
106
+ def self.resolve_typed_items(schema)
67
107
  items = schema[:items]
68
- return [nil, nil] unless items.is_a?(Hash)
69
- return [nil, Riffer::Params.from_json_schema(items)] if items[:properties]
108
+ return unless items.is_a?(Hash)
109
+
110
+ dimensions = 1
111
+ # Riffer only writes nested arrays with enum/format and a single primitive type on the innermost
112
+ # items, and no nullable inner arrays; any other shape would read back with a different meaning.
113
+ while json_type_to_ruby(items[:type]) == Array
114
+ inner = items[:items]
115
+ unless items[:type] == "array" && inner.is_a?(Hash) && !items.keys.intersect?(%i[enum format])
116
+ raise Riffer::ArgumentError, "Unsupported nested array: #{items.to_json}"
117
+ end
118
+
119
+ items = inner
120
+ dimensions += 1
121
+ end
70
122
 
71
- [json_type_to_ruby(items[:type]), nil]
123
+ item_type = json_type_to_ruby(items[:type])
124
+ if dimensions > 1
125
+ if schema.keys.intersect?(%i[enum format])
126
+ raise Riffer::ArgumentError, "Unsupported nested array: #{schema.to_json}"
127
+ end
128
+ unless items[:type].is_a?(String) && PRIMITIVE_TYPES.include?(item_type)
129
+ raise Riffer::ArgumentError, "Unsupported nested array items: #{items.to_json}"
130
+ end
131
+ end
132
+
133
+ [item_type, dimensions, items]
72
134
  end
73
- private_class_method :resolve_nesting
135
+ private_class_method :resolve_typed_items
74
136
 
75
137
  #--
76
138
  #: (untyped) -> Module
77
139
  def self.json_type_to_ruby(type)
78
- key = type.is_a?(Array) ? type.find { |t| t != "null" } : type
79
- JSON_TYPE_MAPPINGS.fetch(key) { raise Riffer::ArgumentError, "Unsupported JSON Schema type: #{type.inspect}" }
140
+ types = Array(type) - ["null"]
141
+ ruby_type = JSON_TYPE_MAPPINGS[types.first] if types.one?
142
+ ruby_type || raise(Riffer::ArgumentError, "Unsupported JSON Schema type: #{type.inspect}")
80
143
  end
81
144
  private_class_method :json_type_to_ruby
82
145
 
83
146
  #--
84
- #: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Module?, ?nested_params: Riffer::Params?) -> void
85
- def initialize(name:, type:, required:, description: nil, enum: nil, default: nil, item_type: nil, nested_params: nil)
147
+ #: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?item_type: Module?, ?dimensions: Integer, ?nested_params: Riffer::Params?, ?variants: Array[Riffer::Params | Riffer::Params::Param]?) -> void
148
+ def initialize(name:, type:, required:, description: nil, enum: nil, format: nil, default: nil, item_type: nil,
149
+ dimensions: 1, nested_params: nil, variants: nil)
150
+ if type == Riffer::Params::AnyOf && variants.nil?
151
+ raise Riffer::ArgumentError, "#{name}: an AnyOf param requires variants"
152
+ end
153
+
86
154
  @name = name.to_sym
87
155
  @type = type
88
156
  @required = required
89
157
  @description = description
90
158
  @enum = enum
159
+ # Frozen and deduplicated, so copies never share a mutable string.
160
+ @format = format.is_a?(String) ? -format : format
91
161
  @default = default
92
162
  @item_type = item_type
163
+ @dimensions = dimensions
93
164
  @nested_params = nested_params
165
+ @variants = variants
166
+ # Checked here rather than in Params so from_json_schema enforces them too.
167
+ validate_format! if format
168
+ validate_variant_order! if variants
94
169
  end
95
170
 
96
171
  #--
@@ -102,6 +177,8 @@ class Riffer::Params::Param
102
177
  [true, false].include?(value)
103
178
  elsif type == Float
104
179
  value.is_a?(Numeric)
180
+ elsif type == Riffer::Params::AnyOf
181
+ Array(variants).any? { |variant| variant.is_a?(Riffer::Params) ? value.is_a?(Hash) : variant.valid_type?(value) }
105
182
  else
106
183
  value.is_a?(type)
107
184
  end
@@ -110,6 +187,11 @@ class Riffer::Params::Param
110
187
  #--
111
188
  #: () -> String
112
189
  def type_name
190
+ if type == Riffer::Params::AnyOf
191
+ names = Array(variants).map { |variant| variant.is_a?(Riffer::Params) ? "object" : variant.type_name }
192
+ return names.uniq.join(" or ")
193
+ end
194
+
113
195
  TYPE_MAPPINGS[type] || type.to_s.downcase
114
196
  end
115
197
 
@@ -120,9 +202,21 @@ class Riffer::Params::Param
120
202
  # Nullable so strict providers can distinguish absent from present.
121
203
  nullable = strict && !required
122
204
 
205
+ if type == Riffer::Params::AnyOf && variants
206
+ schema = { anyOf: variants.map { |variant| variant.to_json_schema(strict: strict) } } #: Hash[Symbol, untyped]
207
+ schema[:anyOf] << { type: "null" } if nullable
208
+ schema[:description] = description if description
209
+ schema[:default] = default unless strict || default.nil?
210
+ return schema
211
+ end
212
+
213
+ # A typed array's enum and format constrain its items, not the array.
214
+ value_enum = enum unless item_type
215
+ value_format = format unless item_type
216
+
123
217
  # Providers like Anthropic reject a nullable type union combined with enum.
124
- if nullable && enum
125
- schema = { anyOf: [{ type: type_name, enum: enum }, { type: "null" }] } #: Hash[Symbol, untyped]
218
+ if nullable && value_enum
219
+ schema = { anyOf: [{ type: type_name, enum: value_enum }, { type: "null" }] } #: Hash[Symbol, untyped]
126
220
  schema[:description] = description if description
127
221
  return schema
128
222
  end
@@ -132,7 +226,8 @@ class Riffer::Params::Param
132
226
 
133
227
  schema = { type: type } #: Hash[Symbol, untyped]
134
228
  schema[:description] = description if description
135
- schema[:enum] = enum if enum
229
+ schema[:enum] = value_enum if value_enum
230
+ schema[:format] = value_format if value_format
136
231
  # Strict providers reject the +default+ keyword; emit it only in
137
232
  # non-strict mode, where it makes the schema a lossless round-trip
138
233
  # source for +from_json_schema+.
@@ -141,7 +236,9 @@ class Riffer::Params::Param
141
236
  if self.type == Array && nested_params
142
237
  schema[:items] = nested_params.to_json_schema(strict: strict)
143
238
  elsif self.type == Array && item_type
144
- schema[:items] = { type: TYPE_MAPPINGS[item_type] }
239
+ items = { type: TYPE_MAPPINGS[item_type], enum: enum, format: format }.compact #: Hash[Symbol, untyped]
240
+ (dimensions - 1).times { items = { type: "array", items: items } }
241
+ schema[:items] = items
145
242
  elsif self.type == Hash && nested_params
146
243
  # The nested schema carries its own type: "object", which would clobber a nullable union.
147
244
  schema.merge!(nested_params.to_json_schema(strict: strict).except(:type))
@@ -160,10 +257,37 @@ class Riffer::Params::Param
160
257
  def initialize_copy(source)
161
258
  super
162
259
  @nested_params = source.nested_params&.dup
260
+ @variants = source.variants&.map(&:dup)
163
261
  @enum = Riffer::Helpers::DeepDup.call(source.enum)
164
262
  @default = Riffer::Helpers::DeepDup.call(source.default)
165
263
  end
166
264
 
265
+ # The first matching variant wins, and a Float variant without an enum accepts any number.
266
+ #--
267
+ #: () -> void
268
+ def validate_variant_order!
269
+ primitives = Array(variants).grep(Riffer::Params::Param) #: Array[Riffer::Params::Param]
270
+ float = primitives.index { |variant| variant.type == Float && variant.enum.nil? }
271
+ integer = primitives.rindex { |variant| variant.type == Integer }
272
+ return unless float && integer && float < integer
273
+
274
+ raise Riffer::ArgumentError, "#{name}: an Integer variant after a Float variant without enum: can never match"
275
+ end
276
+
277
+ #--
278
+ #: () -> void
279
+ def validate_format!
280
+ unless Riffer::Params::Format::NAMES.include?(format)
281
+ raise Riffer::ArgumentError,
282
+ "#{name}: format: must be a supported format (#{Riffer::Params::Format::NAMES.join(', ')}), " \
283
+ "got #{format.inspect}"
284
+ end
285
+ unless type == String || (type == Array && item_type == String)
286
+ raise Riffer::ArgumentError, "#{name}: format: requires a String or an Array whose innermost type is String"
287
+ end
288
+ raise Riffer::ArgumentError, "#{name}: format: cannot be used with enum:" if enum
289
+ end
290
+
167
291
  #--
168
292
  #: () -> void
169
293
  def validate_strict_shape!