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
@@ -1,12 +1,23 @@
1
1
  # frozen_string_literal: true
2
2
  # rbs_inline: enabled
3
3
 
4
+ require "digest"
4
5
  require "json"
5
6
  require "securerandom"
6
7
 
7
8
  class Riffer::Providers::Gemini < Riffer::Providers::Base
8
9
  VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._-]+\z/ #: Regexp
9
10
 
11
+ REASONING_FORMAT = "gemini-generate-content-v1" #: String
12
+
13
+ GEMINI_CALL_ID_PATTERN = /\Agemini_call_\h{24}_(.+)\z/ #: Regexp
14
+
15
+ WEB_SEARCH_TOOL_TYPE = "GOOGLE_SEARCH_WEB" #: String
16
+
17
+ # Gemini's documented stand-in for a function call it didn't sign, such as
18
+ # one another provider made. Without a signature it rejects the call.
19
+ PLACEHOLDER_SIGNATURE = "skip_thought_signature_validator" #: String
20
+
10
21
  FINISH_REASONS = {
11
22
  "STOP" => :stop,
12
23
  "MAX_TOKENS" => :length,
@@ -51,7 +62,16 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
51
62
  #--
52
63
  #: () -> untyped
53
64
  def build_client
54
- Riffer::Providers::Gemini::Client.new(**{ api_key: Riffer.config.gemini.api_key }.compact)
65
+ config = Riffer.config.gemini
66
+ api_key = config.api_key || ENV.fetch("GEMINI_API_KEY", nil)
67
+ unless api_key
68
+ raise Riffer::ArgumentError, "Gemini requires an API key: set config.gemini.api_key or GEMINI_API_KEY"
69
+ end
70
+
71
+ Riffer::Providers::Gemini::Client.new(
72
+ api_key: api_key,
73
+ base_url: config.base_url || Riffer::Providers::Gemini::Client::DEFAULT_BASE_URL,
74
+ )
55
75
  end
56
76
 
57
77
  #--
@@ -66,6 +86,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
66
86
  partitioned = partition_messages(messages)
67
87
  tools = options[:tools]
68
88
  structured_output = options[:structured_output]
89
+ web_search = options[:web_search]
69
90
 
70
91
  params = {
71
92
  model: model,
@@ -74,26 +95,46 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
74
95
 
75
96
  params[:systemInstruction] = partitioned[:system_instruction] if partitioned[:system_instruction]
76
97
 
98
+ gemini_tools = [] #: Array[Hash[Symbol, untyped]]
77
99
  if tools && !tools.empty?
78
- params[:tools] = [{
79
- functionDeclarations: tools.map { |t| convert_tool_to_gemini_format(t) },
80
- }]
100
+ gemini_tools << { functionDeclarations: tools.map { |t| convert_tool_to_gemini_format(t) } }
81
101
  end
102
+ gemini_tools << web_search_tool(web_search) if web_search
103
+ params[:tools] = gemini_tools unless gemini_tools.empty?
104
+
105
+ # The Developer API rejects Google Search next to function declarations
106
+ # unless it also returns the search as toolCall/toolResponse parts. Those
107
+ # parts carry the queries mid-stream, so it is on whenever search is.
108
+ params[:toolConfig] = { includeServerSideToolInvocations: true } if web_search
82
109
 
83
110
  # The Gemini Developer API has no request labels field and rejects unknown
84
111
  # body fields, so :tags reach observability only.
85
- generation_config = options.except(:tools, :structured_output, :tags)
112
+ generation_config = options.except(:tools, :structured_output, :web_search, :tags)
86
113
 
87
- if structured_output
88
- generation_config[:responseMimeType] = "application/json"
89
- generation_config[:responseSchema] = strip_additional_properties(structured_output.json_schema)
90
- end
114
+ # Strict, so an optional field is nullable and the model can leave it
115
+ # empty instead of making a value up.
116
+ schema = structured_output&.json_schema(strict: true)
117
+ generation_config.merge!(structured_output_config(schema)) if schema
91
118
 
92
119
  params[:generationConfig] = generation_config unless generation_config.empty?
93
120
 
94
121
  params
95
122
  end
96
123
 
124
+ #--
125
+ #: (true | Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
126
+ def web_search_tool(web_search)
127
+ { googleSearch: web_search.is_a?(Hash) ? web_search : {} }
128
+ end
129
+
130
+ # gemini-2.x models on the Developer API silently ignore responseFormat and
131
+ # return prose; structured output needs gemini-3 or later.
132
+ #--
133
+ #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
134
+ def structured_output_config(json_schema)
135
+ { responseFormat: { text: { mimeType: "APPLICATION_JSON", schema: json_schema } } }
136
+ end
137
+
97
138
  #--
98
139
  #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
99
140
  def execute_generate(params)
@@ -122,13 +163,71 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
122
163
 
123
164
  fc = part[:functionCall]
124
165
  Riffer::Messages::Assistant::ToolCall.new(
125
- call_id: "gemini_call_#{SecureRandom.hex(12)}",
166
+ call_id: tool_call_id(part),
126
167
  name: fc[:name],
127
168
  arguments: encode_tool_arguments(fc[:args]),
128
169
  )
129
170
  end
130
171
  end
131
172
 
173
+ #--
174
+ #: (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::ReasoningPart]
175
+ def extract_reasoning(response)
176
+ parts = response.dig(:candidates, 0, :content, :parts)
177
+ return [] unless parts
178
+
179
+ parts.filter_map { |part| build_signature_part(part) }
180
+ end
181
+
182
+ # Gemini 3 needs each thoughtSignature back on the part it came on, and
183
+ # rejects a function call in the current turn that lost it. The reasoning
184
+ # part's id names the tool call it belongs to; nil means the text.
185
+ #--
186
+ #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
187
+ def build_signature_part(part)
188
+ signature = part[:thoughtSignature]
189
+ return unless signature
190
+ # Search toolCall/toolResponse parts aren't replayed, so neither are their
191
+ # signatures. Without them in the history Gemini searches again.
192
+ return if part[:toolCall] || part[:toolResponse]
193
+
194
+ Riffer::Messages::Assistant::ReasoningPart.new(
195
+ type: :encrypted,
196
+ data: signature,
197
+ id: part[:functionCall] ? tool_call_id(part) : nil,
198
+ format: reasoning_format,
199
+ )
200
+ end
201
+
202
+ # Distinct from GoogleCloud's: the Developer API and Agent Platform each
203
+ # reject the other's signatures.
204
+ #--
205
+ #: () -> String
206
+ def reasoning_format
207
+ REASONING_FORMAT
208
+ end
209
+
210
+ # Gemini's own call ids are too short to stay unique across a session, so
211
+ # riffer makes its own and appends Gemini's, which gemini_call_id reads back
212
+ # on replay. A signed call's id comes from its signature, so
213
+ # extract_tool_calls and extract_reasoning agree on it.
214
+ #--
215
+ #: (Hash[Symbol, untyped]) -> String
216
+ def tool_call_id(part)
217
+ signature = part[:thoughtSignature]
218
+ suffix = signature ? Digest::SHA256.hexdigest(signature)[0, 24] : SecureRandom.hex(12)
219
+ gemini_id = part.dig(:functionCall, :id)
220
+ gemini_id ? "gemini_call_#{suffix}_#{gemini_id}" : "gemini_call_#{suffix}"
221
+ end
222
+
223
+ # Gemini matches each functionResponse to its functionCall by this id, which
224
+ # parallel calls to the same function need.
225
+ #--
226
+ #: (String) -> String?
227
+ def gemini_call_id(call_id)
228
+ call_id[GEMINI_CALL_ID_PATTERN, 1]
229
+ end
230
+
132
231
  #--
133
232
  #: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage?
134
233
  def extract_token_usage(response)
@@ -178,58 +277,86 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
178
277
  body = params.except(:model)
179
278
 
180
279
  full_text = +""
181
- buffer = +""
182
280
  raw_finish_reason = nil #: String?
281
+ usage = nil #: Hash[Symbol, untyped]?
183
282
  saw_function_call = false
184
-
185
- process_chunk = lambda do |chunk|
186
- buffer << chunk
187
-
188
- while (match = buffer.match(/\r?\n\r?\n/))
189
- match_end = match.end(0) #: Integer
190
- frame = buffer.slice!(0, match_end).to_s.strip
191
- next unless frame.start_with?("data: ")
192
-
193
- json_str = frame.delete_prefix("data: ").strip
194
- next if json_str.empty?
195
-
196
- parsed = JSON.parse(json_str, symbolize_names: true)
197
- parts = parsed.dig(:candidates, 0, :content, :parts)
198
-
199
- parts&.each do |part|
200
- if part[:text]
201
- full_text << part[:text]
202
- yielder << Riffer::StreamEvents::TextDelta.new(part[:text])
203
- elsif part[:functionCall]
204
- fc = part[:functionCall]
205
- saw_function_call = true
206
- call_id = "gemini_call_#{SecureRandom.hex(12)}"
207
- arguments = encode_tool_arguments(fc[:args])
208
- yielder << Riffer::StreamEvents::ToolCallDone.new(
209
- item_id: call_id,
210
- call_id: call_id,
211
- name: fc[:name],
212
- arguments: arguments,
213
- )
214
- end
283
+ decoder = Riffer::Wire::SSE.new
284
+
285
+ process_data = lambda do |data|
286
+ return if data.empty?
287
+
288
+ parsed = JSON.parse(data, symbolize_names: true)
289
+ parts = parsed.dig(:candidates, 0, :content, :parts)
290
+
291
+ parts&.each do |part|
292
+ if part[:text]
293
+ full_text << part[:text]
294
+ yielder << Riffer::StreamEvents::TextDelta.new(part[:text])
295
+ elsif part[:functionCall]
296
+ fc = part[:functionCall]
297
+ saw_function_call = true
298
+ call_id = tool_call_id(part)
299
+ arguments = encode_tool_arguments(fc[:args])
300
+ yielder << Riffer::StreamEvents::ToolCallDone.new(
301
+ item_id: call_id,
302
+ call_id: call_id,
303
+ name: fc[:name],
304
+ arguments: arguments,
305
+ )
306
+ elsif part[:toolCall]
307
+ yield_web_search_queries(part[:toolCall], yielder)
308
+ elsif part.dig(:toolResponse, :toolType) == WEB_SEARCH_TOOL_TYPE
309
+ yielder << Riffer::StreamEvents::WebSearchStatus.new("completed")
215
310
  end
216
311
 
217
- raw_finish_reason = parsed.dig(:candidates, 0, :finishReason) || raw_finish_reason
218
-
219
- usage = parsed[:usageMetadata]
220
- if usage && usage[:candidatesTokenCount]
221
- yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: build_token_usage(usage))
222
- end
312
+ signature_part = build_signature_part(part)
313
+ yielder << Riffer::StreamEvents::ReasoningDone.new(signature_part) if signature_part
223
314
  end
315
+
316
+ grounding = parsed.dig(:candidates, 0, :groundingMetadata)
317
+ yield_web_search_done(grounding, yielder) if grounding
318
+
319
+ raw_finish_reason = parsed.dig(:candidates, 0, :finishReason) || raw_finish_reason
320
+
321
+ # Every chunk repeats the running totals; the last one holds the final count.
322
+ usage = parsed[:usageMetadata] || usage
224
323
  end
225
324
 
226
325
  path = "#{api_path(model, 'streamGenerateContent')}?alt=sse"
227
- client.post_stream(path, body) { |chunk| process_chunk.call(chunk) }
326
+ client.post_stream(path, body) { |chunk| decoder.feed(chunk) { |data, _event| process_data.call(data) } }
228
327
 
229
328
  yielder << Riffer::StreamEvents::TextDone.new(full_text) unless full_text.empty?
329
+ yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: build_token_usage(usage)) if usage
230
330
  yield_finish_reason(yielder, build_finish_reason(raw_finish_reason, tool_calls: saw_function_call))
231
331
  end
232
332
 
333
+ #--
334
+ #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
335
+ def yield_web_search_queries(tool_call, yielder)
336
+ return unless tool_call[:toolType] == WEB_SEARCH_TOOL_TYPE
337
+
338
+ queries = tool_call.dig(:args, :queries) || [] #: Array[String]
339
+ queries.each do |query|
340
+ yielder << Riffer::StreamEvents::WebSearchStatus.new("searching", query: query)
341
+ end
342
+ end
343
+
344
+ # Gemini reports every query and source of the turn together, without saying
345
+ # which query found which source, so they become one WebSearchDone.
346
+ #--
347
+ #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
348
+ def yield_web_search_done(grounding, yielder)
349
+ queries = grounding[:webSearchQueries] || []
350
+ return if queries.empty?
351
+
352
+ chunks = grounding[:groundingChunks] || [] #: Array[Hash[Symbol, untyped]]
353
+ sources = chunks.filter_map do |chunk|
354
+ web = chunk[:web]
355
+ { title: web[:title], url: web[:uri] } if web
356
+ end
357
+ yielder << Riffer::StreamEvents::WebSearchDone.new(queries.join(", "), sources: sources)
358
+ end
359
+
233
360
  #--
234
361
  #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
235
362
  def partition_messages(messages)
@@ -251,15 +378,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
251
378
  when Riffer::Messages::Assistant
252
379
  contents << convert_assistant_to_gemini_format(message)
253
380
  when Riffer::Messages::Tool
254
- contents << {
255
- role: "user",
256
- parts: [{
257
- functionResponse: {
258
- name: message.name,
259
- response: { result: message.content },
260
- },
261
- }],
262
- }
381
+ append_tool_result(contents, message)
263
382
  end
264
383
  end
265
384
 
@@ -268,19 +387,50 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
268
387
  result
269
388
  end
270
389
 
390
+ # Gemini needs every result for one call turn in a single content, one part each.
391
+ #--
392
+ #: (Array[Hash[Symbol, untyped]], Riffer::Messages::Tool) -> void
393
+ def append_tool_result(contents, message)
394
+ part = {
395
+ functionResponse: {
396
+ id: gemini_call_id(message.tool_call_id),
397
+ name: message.name,
398
+ response: { result: message.content },
399
+ }.compact,
400
+ }
401
+
402
+ prev = contents.last
403
+ if prev && prev[:role] == "user" && prev[:parts].first&.key?(:functionResponse)
404
+ prev[:parts] << part
405
+ else
406
+ contents << { role: "user", parts: [part] }
407
+ end
408
+ end
409
+
271
410
  #--
272
411
  #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
273
412
  def convert_assistant_to_gemini_format(message)
413
+ signature_parts = message.reasoning.select { |part| part.format == reasoning_format }
414
+ text_signature = signature_parts.find { |part| part.id.nil? }&.data
415
+ call_signatures = signature_parts.select(&:id).to_h { |part| [part.id, part.data] }
416
+
274
417
  parts = [] #: Array[Hash[Symbol, untyped]]
275
- parts << { text: message.content } if message.content && !message.content.empty?
418
+ if message.content && !message.content.empty?
419
+ parts << { text: message.content, thoughtSignature: text_signature }.compact
420
+ end
276
421
 
277
- message.tool_calls.each do |tc|
422
+ message.tool_calls.each_with_index do |tc, index|
423
+ signature = call_signatures[tc.call_id]
424
+ # Gemini requires a signature on the first call of a step.
425
+ signature ||= PLACEHOLDER_SIGNATURE if index.zero?
278
426
  parts << {
279
427
  functionCall: {
428
+ id: gemini_call_id(tc.call_id),
280
429
  name: tc.name,
281
430
  args: parse_tool_arguments(tc.arguments),
282
- },
283
- }
431
+ }.compact,
432
+ thoughtSignature: signature,
433
+ }.compact
284
434
  end
285
435
 
286
436
  { role: "model", parts: parts }
@@ -298,7 +448,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
298
448
  {
299
449
  name: tool.name,
300
450
  description: tool.description,
301
- parameters: strip_additional_properties(tool.parameters_schema),
451
+ parametersJsonSchema: tool.parameters_schema,
302
452
  }
303
453
  end
304
454
 
@@ -326,21 +476,4 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
326
476
  "Invalid model name: #{model.inspect}. Model must contain only alphanumeric characters, " \
327
477
  "hyphens, dots, and underscores."
328
478
  end
329
-
330
- #--
331
- #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
332
- def strip_additional_properties(schema)
333
- schema = schema.dup
334
- schema.delete(:additionalProperties)
335
-
336
- if schema[:properties]
337
- schema[:properties] = schema[:properties].transform_values do |prop|
338
- strip_additional_properties(prop)
339
- end
340
- end
341
-
342
- schema[:items] = strip_additional_properties(schema[:items]) if schema[:items].is_a?(Hash)
343
-
344
- schema
345
- end
346
479
  end
@@ -0,0 +1,106 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ # <tt>Riffer.config.google_cloud.client</tt> accepts any object implementing +post+ and +post_stream+
5
+ # (see Riffer::HTTP::Client); this class is the default, not a required base. Paths are relative to
6
+ # the client's <tt>v1/projects/{project_id}/locations/{location}</tt> resource.
7
+ class Riffer::Providers::GoogleCloud::Client < Riffer::HTTP::Client
8
+ # @rbs @project_id: String
9
+ # @rbs @location: String
10
+ # @rbs @credentials: untyped
11
+ # @rbs @base_url: String
12
+ # @rbs self.@application_default_credentials: untyped
13
+
14
+ SCOPE = "https://www.googleapis.com/auth/cloud-platform" #: String
15
+
16
+ # Both are interpolated into the endpoint's host or path.
17
+ VALID_PROJECT_ID_PATTERN = /\A[a-z0-9.:-]+\z/ #: Regexp
18
+ VALID_LOCATION_PATTERN = /\A[a-z0-9-]+\z/ #: Regexp
19
+
20
+ # googleauth's metadata-server lookups (GCE, Cloud Run, GKE) go through a
21
+ # process-wide google-cloud-env cache that detects reentrancy by Thread, so
22
+ # two fibers inside it at once raise ThreadError. Every googleauth call that
23
+ # can reach it holds this lock; Ruby's Mutex is fiber-aware, so waiters yield
24
+ # to the scheduler instead of blocking the thread.
25
+ AUTH_LOCK = Mutex.new #: Thread::Mutex
26
+
27
+ # Memoized process-wide so every client shares one token cache.
28
+ #--
29
+ #: () -> untyped
30
+ def self.application_default_credentials
31
+ AUTH_LOCK.synchronize do
32
+ @application_default_credentials ||= begin
33
+ Riffer::Helpers::Dependencies.depends_on("googleauth")
34
+ Google::Auth.get_application_default([SCOPE])
35
+ end
36
+ end
37
+ end
38
+
39
+ #--
40
+ #: (location: String) -> String
41
+ def self.base_url_for(location:)
42
+ case location
43
+ when "global" then "https://aiplatform.googleapis.com"
44
+ when "us", "eu" then "https://aiplatform.#{location}.rep.googleapis.com"
45
+ else "https://#{location}-aiplatform.googleapis.com"
46
+ end
47
+ end
48
+
49
+ #--
50
+ #: (Riffer::Config::GoogleCloud) -> Riffer::Providers::GoogleCloud::Client
51
+ def self.from_config(config)
52
+ project_id = config.project_id
53
+ raise Riffer::ArgumentError, "Riffer.config.google_cloud.project_id must be set" unless project_id
54
+
55
+ new(project_id: project_id, location: config.location, credentials: config.credentials)
56
+ end
57
+
58
+ # +credentials+ is a googleauth credentials object (anything responding to
59
+ # +updater_proc+); +nil+ resolves Application Default Credentials.
60
+ #--
61
+ #: (project_id: String, location: String, ?credentials: untyped, ?base_url: String?, ?headers: Hash[String, String], ?connection: Faraday::Connection?) -> void
62
+ def initialize(project_id:, location:, credentials: nil, base_url: nil, headers: {}, connection: nil)
63
+ validate!(project_id, VALID_PROJECT_ID_PATTERN, "project_id")
64
+ validate!(location, VALID_LOCATION_PATTERN, "location")
65
+ super(headers: headers, connection: connection)
66
+
67
+ @project_id = project_id
68
+ @location = location
69
+ @credentials = credentials
70
+ @base_url = (base_url || self.class.base_url_for(location: location)).chomp("/")
71
+ end
72
+
73
+ private
74
+
75
+ #--
76
+ #: (String, Regexp, String) -> void
77
+ def validate!(value, pattern, attribute)
78
+ return if value.is_a?(String) && value.match?(pattern)
79
+
80
+ raise Riffer::ArgumentError, "Invalid #{attribute}: #{value.inspect}"
81
+ end
82
+
83
+ #--
84
+ #: (String) -> String
85
+ def url_for(path)
86
+ "#{@base_url}/v1/projects/#{@project_id}/locations/#{@location}/#{path}"
87
+ end
88
+
89
+ # googleauth refreshes only a missing or near-expiry token, so fibers queued
90
+ # behind a refresh reuse its result. +updater_proc+ rather than +apply!+,
91
+ # whose return value is the header String for some credential types and the
92
+ # headers Hash for others (self-signed JWTs).
93
+ #--
94
+ #: () -> Hash[String, String]
95
+ def headers
96
+ credentials = @credentials || self.class.application_default_credentials
97
+ auth = {} #: Hash[Symbol, String]
98
+ AUTH_LOCK.synchronize { credentials.updater_proc.call(auth) }.transform_keys(&:to_s)
99
+ end
100
+
101
+ #--
102
+ #: () -> String
103
+ def error_label
104
+ "Google Cloud"
105
+ end
106
+ end
@@ -0,0 +1,99 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ # Gemini models on Gemini Enterprise Agent Platform (formerly Vertex AI). The
5
+ # request and response bodies match the Gemini Developer API's, so this only
6
+ # swaps the transport, the resource paths and the structured output field.
7
+ class Riffer::Providers::GoogleCloud < Riffer::Providers::Gemini
8
+ # Agent Platform model ids may carry an +@version+ suffix.
9
+ VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._@-]+\z/ #: Regexp
10
+
11
+ REASONING_FORMAT = "google-cloud-generate-content-v1" #: String
12
+
13
+ # Agent Platform label keys and values: at most 63 characters of lowercase
14
+ # letters, digits, underscores and dashes; keys start with a letter.
15
+ LABEL_MAX_LENGTH = 63 #: Integer
16
+ LABEL_INVALID_CHARACTERS = /[^\p{Ll}\p{Lo}\p{N}_-]/ #: Regexp
17
+
18
+ #--
19
+ #: () -> String
20
+ def self.semconv_provider_name
21
+ "gcp.vertex_ai"
22
+ end
23
+
24
+ private
25
+
26
+ #--
27
+ #: () -> untyped
28
+ def global_client
29
+ Riffer.config.google_cloud.client
30
+ end
31
+
32
+ #--
33
+ #: () -> untyped
34
+ def build_client
35
+ Riffer::Providers::GoogleCloud::Client.from_config(Riffer.config.google_cloud)
36
+ end
37
+
38
+ # Tags go out as request labels, merged over any +labels+ model option.
39
+ #--
40
+ #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
41
+ def build_request_params(messages, model, options)
42
+ params = super(messages, model, options.except(:labels))
43
+ labels = (options[:labels] || {}).transform_keys(&:to_s).merge(tag_labels(options[:tags] || {}))
44
+ params[:labels] = labels unless labels.empty?
45
+ params
46
+ end
47
+
48
+ # Rewrites tags into valid labels (downcased, invalid characters replaced by
49
+ # an underscore, cut to 63 characters) and drops keys that don't start with
50
+ # a letter, so a tag like agent: "support/triage_agent" can't fail the call.
51
+ #--
52
+ #: (Hash[untyped, untyped]) -> Hash[String, String]
53
+ def tag_labels(tags)
54
+ labels = {} #: Hash[String, String]
55
+ tags.each do |key, value|
56
+ next if value.nil?
57
+
58
+ label_key = to_label(key)
59
+ labels[label_key] = to_label(value) if label_key.match?(/\A\p{L}/)
60
+ end
61
+ labels
62
+ end
63
+
64
+ #--
65
+ #: (untyped) -> String
66
+ def to_label(value)
67
+ value.to_s.downcase.gsub(LABEL_INVALID_CHARACTERS, "_")[0, LABEL_MAX_LENGTH].to_s
68
+ end
69
+
70
+ #--
71
+ #: () -> String
72
+ def reasoning_format
73
+ REASONING_FORMAT
74
+ end
75
+
76
+ # Agent Platform declares responseFormat as a repeated field.
77
+ #--
78
+ #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
79
+ def structured_output_config(json_schema)
80
+ { responseFormat: [{ text: { mimeType: "APPLICATION_JSON", schema: json_schema } }] }
81
+ end
82
+
83
+ #--
84
+ #: (String, String) -> String
85
+ def api_path(model, method)
86
+ validate_model!(model)
87
+ "publishers/google/models/#{model}:#{method}"
88
+ end
89
+
90
+ #--
91
+ #: (String) -> void
92
+ def validate_model!(model)
93
+ return if model.match?(VALID_MODEL_PATTERN)
94
+
95
+ raise Riffer::ArgumentError,
96
+ "Invalid model name: #{model.inspect}. Model must contain only alphanumeric characters, " \
97
+ "hyphens, dots, underscores, and @."
98
+ end
99
+ end
@@ -10,8 +10,10 @@ module Riffer::Providers::Repository
10
10
  REPO = {
11
11
  amazon_bedrock: -> { Riffer::Providers::AmazonBedrock },
12
12
  anthropic: -> { Riffer::Providers::Anthropic },
13
+ anthropic_vertex: -> { Riffer::Providers::AnthropicVertex },
13
14
  azure_openai: -> { Riffer::Providers::AzureOpenAI },
14
15
  gemini: -> { Riffer::Providers::Gemini },
16
+ google_cloud: -> { Riffer::Providers::GoogleCloud },
15
17
  openai: -> { Riffer::Providers::OpenAI },
16
18
  openrouter: -> { Riffer::Providers::OpenRouter },
17
19
  mock: -> { Riffer::Providers::Mock },
@@ -2,5 +2,5 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module Riffer
5
- VERSION = "0.53.0" #: String
5
+ VERSION = "0.55.0" #: String
6
6
  end
@@ -0,0 +1,51 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Wire::SSE
5
+ # @rbs @buffer: String
6
+ # @rbs @data: Array[String]
7
+ # @rbs @event: String?
8
+
9
+ #--
10
+ #: () -> void
11
+ def initialize
12
+ @buffer = +""
13
+ @data = []
14
+ @event = nil
15
+ end
16
+
17
+ #--
18
+ #: (String) { (String, String?) -> void } -> void
19
+ def feed(chunk, &)
20
+ @buffer << chunk
21
+
22
+ # Lines end in LF or CRLF. The SSE spec also allows a bare CR, which no
23
+ # supported provider sends.
24
+ while (line_end = @buffer.index("\n"))
25
+ line = @buffer.slice!(0, line_end + 1).to_s.chomp
26
+ process_line(line, &)
27
+ end
28
+ end
29
+
30
+ private
31
+
32
+ #--
33
+ #: (String) { (String, String?) -> void } -> void
34
+ def process_line(line)
35
+ if line.empty?
36
+ yield(@data.join("\n"), @event) unless @data.empty?
37
+ @data = []
38
+ @event = nil
39
+ return
40
+ end
41
+ return if line.start_with?(":")
42
+
43
+ field, value = line.split(":", 2)
44
+ value = value.to_s.delete_prefix(" ")
45
+
46
+ case field
47
+ when "data" then @data << value
48
+ when "event" then @event = value
49
+ end
50
+ end
51
+ end