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
data/lib/riffer/params.rb CHANGED
@@ -29,33 +29,45 @@ class Riffer::Params
29
29
  end
30
30
 
31
31
  #--
32
- #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
33
- def required(name, type, description: nil, enum: nil, of: nil, &)
34
- nested = build_nested(type, of, &)
32
+ #: (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
33
+ #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
34
+ def required(name, type, description: nil, enum: nil, format: nil, of: nil, &)
35
+ item_type, dimensions = unwrap_of(of)
36
+ nested = build_nested(type, item_type, enum, &) unless type == Riffer::Params::AnyOf
37
+ variants = build_variants(name, of, enum, &) if type == Riffer::Params::AnyOf
35
38
  @parameters << Riffer::Params::Param.new(
36
39
  name: name,
37
40
  type: type,
38
41
  required: true,
39
42
  description: description,
40
43
  enum: enum,
41
- item_type: of,
44
+ format: format,
45
+ item_type: item_type,
46
+ dimensions: dimensions,
42
47
  nested_params: nested,
48
+ variants: variants,
43
49
  )
44
50
  end
45
51
 
46
52
  #--
47
- #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
48
- def optional(name, type, description: nil, enum: nil, default: nil, of: nil, &)
49
- nested = build_nested(type, of, &)
53
+ #: (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?, ?default: untyped) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
54
+ #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
55
+ def optional(name, type, description: nil, enum: nil, format: nil, default: nil, of: nil, &)
56
+ item_type, dimensions = unwrap_of(of)
57
+ nested = build_nested(type, item_type, enum, &) unless type == Riffer::Params::AnyOf
58
+ variants = build_variants(name, of, enum, &) if type == Riffer::Params::AnyOf
50
59
  @parameters << Riffer::Params::Param.new(
51
60
  name: name,
52
61
  type: type,
53
62
  required: false,
54
63
  description: description,
55
64
  enum: enum,
65
+ format: format,
56
66
  default: default,
57
- item_type: of,
67
+ item_type: item_type,
68
+ dimensions: dimensions,
58
69
  nested_params: nested,
70
+ variants: variants,
59
71
  )
60
72
  end
61
73
 
@@ -78,13 +90,8 @@ class Riffer::Params
78
90
  next
79
91
  end
80
92
 
81
- unless param.valid_type?(value)
82
- errors << "#{param.name} must be a #{param.type_name}"
83
- next
84
- end
85
-
86
- if param.enum && !param.enum.include?(value)
87
- errors << "#{param.name} must be one of: #{param.enum.join(', ')}"
93
+ if (error = value_error(param, value))
94
+ errors << "#{param.name} #{error}"
88
95
  next
89
96
  end
90
97
 
@@ -131,9 +138,20 @@ class Riffer::Params
131
138
  end
132
139
 
133
140
  #--
134
- #: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
135
- def build_nested(type, of, &block)
141
+ #: ((Module | Array[untyped])?, ?Integer) -> [Module?, Integer]
142
+ def unwrap_of(of, dimensions = 1)
143
+ return [of, dimensions] unless of.is_a?(Array)
144
+ raise Riffer::ArgumentError, "of: must nest exactly one type, got #{of.inspect}" unless of.size == 1 && of.first
145
+
146
+ unwrap_of(of.first, dimensions + 1)
147
+ end
148
+
149
+ #--
150
+ #: (Module, Module?, Array[untyped]?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
151
+ def build_nested(type, of, enum, &block)
136
152
  raise Riffer::ArgumentError, "cannot use both of: and a block" if of && block
153
+ raise Riffer::ArgumentError, "enum: cannot be used with Hash" if enum && type == Hash
154
+ raise Riffer::ArgumentError, "enum: with Array requires of:" if enum && type == Array && !of
137
155
 
138
156
  if of
139
157
  raise Riffer::ArgumentError, "of: can only be used with Array type, got #{type}" unless type == Array
@@ -155,10 +173,39 @@ class Riffer::Params
155
173
  nested
156
174
  end
157
175
 
176
+ #--
177
+ #: (Symbol, (Module | Array[untyped])?, Array[untyped]?) ?{ (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> Array[Riffer::Params | Riffer::Params::Param]
178
+ def build_variants(name, of, enum, &block)
179
+ raise Riffer::ArgumentError, "of: cannot be used with AnyOf" if of
180
+ raise Riffer::ArgumentError, "enum: cannot be used with AnyOf" if enum
181
+ raise Riffer::ArgumentError, "AnyOf requires a block defining its variants" unless block
182
+
183
+ any_of = Riffer::Params::AnyOf.new(name)
184
+ any_of.instance_eval(&block)
185
+ raise Riffer::ArgumentError, "AnyOf requires at least two variants" if any_of.variants.size < 2
186
+
187
+ any_of.variants
188
+ end
189
+
190
+ #--
191
+ #: (Riffer::Params::Param, untyped) -> String?
192
+ def value_error(param, value)
193
+ return "must be a #{param.type_name}" unless param.valid_type?(value)
194
+
195
+ # A typed array's enum and format constrain its items, which validate_typed_array checks.
196
+ return "must be one of: #{param.enum.join(', ')}" if param.enum && !param.item_type && !param.enum.include?(value)
197
+
198
+ return unless param.format && !param.item_type && !Riffer::Params::Format.valid?(param.format, value)
199
+
200
+ "must be a valid #{param.format}"
201
+ end
202
+
158
203
  #--
159
204
  #: (Riffer::Params::Param, untyped, Array[String]) -> untyped
160
205
  def validate_nested(param, value, errors)
161
- if param.type == Hash && param.nested_params
206
+ if param.type == Riffer::Params::AnyOf
207
+ validate_any_of(param, value, errors)
208
+ elsif param.type == Hash && param.nested_params
162
209
  validate_nested_hash(param, value, errors)
163
210
  elsif param.type == Array && param.nested_params
164
211
  validate_nested_array_of_objects(param, value, errors)
@@ -183,6 +230,62 @@ class Riffer::Params
183
230
  value
184
231
  end
185
232
 
233
+ #--
234
+ #: (Riffer::Params::Param, untyped, Array[String]) -> untyped
235
+ def validate_any_of(param, value, errors)
236
+ variants = param.variants
237
+ return value unless variants
238
+
239
+ variant_errors = [] #: Array[String]
240
+ variants.each.with_index(1) do |variant, number|
241
+ if variant.is_a?(Riffer::Params::Param)
242
+ error = value_error(variant, value)
243
+ return coerce_value(variant.type, value) unless error
244
+
245
+ variant_errors << "variant #{number} (#{error})"
246
+ next
247
+ end
248
+
249
+ unless value.is_a?(Hash)
250
+ variant_errors << "variant #{number} (must be a object)"
251
+ next
252
+ end
253
+
254
+ validated = variant.validate(value)
255
+ # Each variant's schema sets additionalProperties: false on every object
256
+ # it declares, so a key outside this variant rules it out.
257
+ unknown = undeclared_keys(value, validated)
258
+ return validated if unknown.empty?
259
+
260
+ variant_errors << "variant #{number} (#{unknown.map { |path| "#{path} is not allowed" }.join(', ')})"
261
+ rescue Riffer::ValidationError => e
262
+ # Enclosing params split errors on "; " to prefix their path, so one
263
+ # variant's errors must not contain it.
264
+ variant_errors << "variant #{number} (#{e.message.gsub('; ', ', ')})"
265
+ end
266
+
267
+ errors << "#{param.name} must match one of the variants: #{variant_errors.join(', ')}"
268
+ value
269
+ end
270
+
271
+ # Validation drops keys a Params doesn't declare, at any depth, so they are
272
+ # the keys in the input that are missing from the output.
273
+ #--
274
+ #: (untyped, untyped, ?String?) -> Array[String]
275
+ def undeclared_keys(value, validated, path = nil)
276
+ case value
277
+ when Hash
278
+ value.flat_map do |key, child|
279
+ key_path = [path, key].compact.join(".")
280
+ validated.key?(key) ? undeclared_keys(child, validated[key], key_path) : [key_path]
281
+ end
282
+ when Array
283
+ value.each_with_index.flat_map { |item, i| undeclared_keys(item, validated[i], "#{path}[#{i}]") }
284
+ else
285
+ []
286
+ end
287
+ end
288
+
186
289
  #--
187
290
  #: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
188
291
  def validate_nested_array_of_objects(param, value, errors)
@@ -204,22 +307,33 @@ class Riffer::Params
204
307
  end
205
308
 
206
309
  #--
207
- #: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
208
- def validate_typed_array(param, value, errors)
310
+ #: (Riffer::Params::Param, Array[untyped], Array[String], ?String, ?Integer) -> Array[untyped]
311
+ def validate_typed_array(param, value, errors, path = param.name.to_s, dimensions = param.dimensions)
209
312
  item_type = param.item_type
210
313
  return value unless item_type
211
314
 
212
- type_name = Riffer::Params::Param::TYPE_MAPPINGS[item_type]
213
- valid_item = if [Riffer::Params::Boolean, TrueClass, FalseClass].include?(item_type)
214
- ->(item) { [true, false].include?(item) }
215
- elsif item_type == Float
216
- ->(item) { item.is_a?(Numeric) }
217
- else
218
- ->(item) { item.is_a?(item_type) }
219
- end
220
315
  value.map.with_index do |item, i|
221
- unless valid_item.call(item)
222
- errors << "#{param.name}[#{i}] must be a #{type_name}"
316
+ item_path = "#{path}[#{i}]"
317
+
318
+ if dimensions > 1
319
+ next validate_typed_array(param, item, errors, item_path, dimensions - 1) if item.is_a?(Array)
320
+
321
+ errors << "#{item_path} must be an array"
322
+ next item
323
+ end
324
+
325
+ unless valid_item?(item_type, item)
326
+ errors << "#{item_path} must be a #{Riffer::Params::Param::TYPE_MAPPINGS[item_type]}"
327
+ next item
328
+ end
329
+
330
+ if param.enum && !param.enum.include?(item)
331
+ errors << "#{item_path} must be one of: #{param.enum.join(', ')}"
332
+ next item
333
+ end
334
+
335
+ if param.format && !Riffer::Params::Format.valid?(param.format, item)
336
+ errors << "#{item_path} must be a valid #{param.format}"
223
337
  next item
224
338
  end
225
339
 
@@ -227,6 +341,18 @@ class Riffer::Params
227
341
  end
228
342
  end
229
343
 
344
+ #--
345
+ #: (Module, untyped) -> bool
346
+ def valid_item?(type, item)
347
+ if [Riffer::Params::Boolean, TrueClass, FalseClass].include?(type)
348
+ [true, false].include?(item)
349
+ elsif type == Float
350
+ item.is_a?(Numeric)
351
+ else
352
+ item.is_a?(type)
353
+ end
354
+ end
355
+
230
356
  #--
231
357
  #: (Module, untyped) -> untyped
232
358
  def coerce_value(type, value)
@@ -428,7 +428,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
428
428
  item_id: tool_call[:id],
429
429
  call_id: tool_call[:id],
430
430
  name: tool_call[:name],
431
- arguments: tool_call[:arguments],
431
+ # Converse streams no input delta for a call without arguments.
432
+ arguments: tool_call[:arguments].empty? ? "{}" : tool_call[:arguments],
432
433
  )
433
434
  state[:tool_call] = nil
434
435
  end
@@ -445,6 +446,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
445
446
  def partition_messages(messages)
446
447
  system_prompts = [] #: Array[Hash[Symbol, untyped]]
447
448
  conversation_messages = [] #: Array[Hash[Symbol, untyped]]
449
+ document_names = [] #: Array[String]
448
450
 
449
451
  messages.each do |message|
450
452
  case message
@@ -452,7 +454,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
452
454
  system_prompts << { text: message.content }
453
455
  when Riffer::Messages::User
454
456
  content = [{ text: message.content }]
455
- message.files.each { |file| content << convert_file_part_to_bedrock_format(file) }
457
+ message.files.each { |file| content << convert_file_part_to_bedrock_format(file, document_names) }
456
458
  conversation_messages << { role: "user", content: content }
457
459
  when Riffer::Messages::Assistant
458
460
  conversation_messages << convert_assistant_to_bedrock_format(message)
@@ -515,9 +517,11 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
515
517
  end
516
518
  end
517
519
 
520
+ # +document_names+ collects the names already used in the request, which
521
+ # Converse requires to be unique across every message.
518
522
  #--
519
- #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
520
- def convert_file_part_to_bedrock_format(file)
523
+ #: (Riffer::Messages::User::FilePart, Array[String]) -> Hash[Symbol, untyped]
524
+ def convert_file_part_to_bedrock_format(file, document_names)
521
525
  format = bedrock_format(file.media_type)
522
526
 
523
527
  source = file.data_bytes ? { bytes: file.data_bytes } : { s3_location: { uri: file.url } }
@@ -525,10 +529,39 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
525
529
  if file.image?
526
530
  { image: { format: format, source: source } }
527
531
  else
528
- { document: { format: format, name: file.filename, source: source } }
532
+ { document: { format: format, name: document_name(file.filename, document_names), source: source } }
529
533
  end
530
534
  end
531
535
 
536
+ DOCUMENT_NAME_LIMIT = 200 #: Integer
537
+ private_constant :DOCUMENT_NAME_LIMIT
538
+
539
+ # Converse allows only alphanumerics, single whitespace, hyphens, parentheses
540
+ # and square brackets in a document name, up to 200 characters, so
541
+ # +invoice.pdf+ is sent as +invoice+ and a repeated name gets a counter:
542
+ # +invoice (2)+.
543
+ #--
544
+ #: (String?, Array[String]) -> String
545
+ def document_name(filename, document_names)
546
+ filename = filename.to_s
547
+ base = File.basename(filename, File.extname(filename)).
548
+ gsub(/[^A-Za-z0-9\s\-()\[\]]+/, "-").
549
+ gsub(/\s+/, " ").
550
+ gsub(/\A[\s-]+|[\s-]+\z/, "")
551
+ base = "document" if base.empty?
552
+
553
+ head = base[0, DOCUMENT_NAME_LIMIT] #: String
554
+ name = head.rstrip
555
+ count = 1
556
+ while document_names.include?(name)
557
+ suffix = " (#{count += 1})"
558
+ head = base[0, DOCUMENT_NAME_LIMIT - suffix.length] #: String
559
+ name = "#{head.rstrip}#{suffix}"
560
+ end
561
+ document_names << name
562
+ name
563
+ end
564
+
532
565
  BEDROCK_FORMAT_MAP = {
533
566
  "image/jpeg" => "jpeg",
534
567
  "image/png" => "png",
@@ -0,0 +1,49 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Providers::Anthropic::Client < Riffer::HTTP::Client
5
+ # @rbs @api_key: String
6
+ # @rbs @base_url: String
7
+
8
+ DEFAULT_BASE_URL = "https://api.anthropic.com" #: String
9
+
10
+ # Override with an anthropic-version entry in +headers+.
11
+ DEFAULT_ANTHROPIC_VERSION = "2026-10-21" #: String
12
+
13
+ #--
14
+ #: (api_key: String, ?base_url: String, ?headers: Hash[String, String], ?connection: Faraday::Connection?) -> void
15
+ def initialize(api_key:, base_url: DEFAULT_BASE_URL, headers: {}, connection: nil)
16
+ super(headers: headers, connection: connection)
17
+ @api_key = api_key
18
+ @base_url = base_url.chomp("/")
19
+ end
20
+
21
+ private
22
+
23
+ #--
24
+ #: (String) -> String
25
+ def url_for(path)
26
+ "#{@base_url}/#{path}"
27
+ end
28
+
29
+ #--
30
+ #: () -> Hash[String, String]
31
+ def headers
32
+ { "authorization" => "Bearer #{@api_key}", "anthropic-version" => DEFAULT_ANTHROPIC_VERSION }
33
+ end
34
+
35
+ #--
36
+ #: () -> String
37
+ def error_label
38
+ "Anthropic"
39
+ end
40
+
41
+ #--
42
+ #: (Hash[Symbol, untyped], String) -> String
43
+ def error_message(parsed, raw)
44
+ error = parsed[:error]
45
+ return super unless error.is_a?(Hash) && error[:type] && error[:message]
46
+
47
+ "#{error[:type]}: #{error[:message]}"
48
+ end
49
+ end