riffer 0.54.0 → 0.56.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 (117) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/rules/rbs-inline.md +6 -6
  3. data/.release-please-manifest.json +1 -1
  4. data/.ruby-version +1 -1
  5. data/CHANGELOG.md +46 -0
  6. data/README.md +26 -1
  7. data/Steepfile +2 -2
  8. data/UPGRADING.md +3 -0
  9. data/docs/AGENTS.md +37 -12
  10. data/docs/AGENT_LIFECYCLE.md +1 -1
  11. data/docs/CATALOG.md +8 -8
  12. data/docs/CONFIGURATION.md +95 -17
  13. data/docs/GUARDRAILS.md +2 -0
  14. data/docs/MCP.md +3 -4
  15. data/docs/MESSAGES.md +112 -15
  16. data/docs/STABILITY.md +32 -0
  17. data/docs/STREAM_EVENTS.md +17 -1
  18. data/docs/TESTING.md +22 -1
  19. data/docs/TOOLS.md +11 -11
  20. data/docs/TRACING.md +1 -1
  21. data/docs/providers/AMAZON_BEDROCK.md +3 -1
  22. data/docs/providers/ANTHROPIC.md +44 -44
  23. data/docs/providers/CUSTOM_PROVIDERS.md +59 -0
  24. data/docs/providers/GEMINI.md +76 -26
  25. data/docs/providers/GOOGLE_CLOUD.md +363 -0
  26. data/docs/providers/MOCK_PROVIDER.md +2 -0
  27. data/docs/providers/OPENAI.md +3 -1
  28. data/docs/providers/PROVIDERS.md +30 -18
  29. data/docs-site/manifest.yml +6 -0
  30. data/lib/riffer/agent/run.rb +28 -13
  31. data/lib/riffer/agent/session.rb +33 -10
  32. data/lib/riffer/agent/structured_output.rb +6 -1
  33. data/lib/riffer/config/anthropic.rb +9 -0
  34. data/lib/riffer/config/future.rb +53 -0
  35. data/lib/riffer/config/gemini.rb +9 -0
  36. data/lib/riffer/config/google_cloud.rb +38 -0
  37. data/lib/riffer/config/pricing.rb +5 -15
  38. data/lib/riffer/config.rb +19 -0
  39. data/lib/riffer/deprecation/event.rb +25 -0
  40. data/lib/riffer/deprecation.rb +60 -0
  41. data/lib/riffer/http/client.rb +141 -0
  42. data/lib/riffer/http.rb +5 -0
  43. data/lib/riffer/mcp/client.rb +0 -1
  44. data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
  45. data/lib/riffer/messages/assistant/text_part.rb +52 -0
  46. data/lib/riffer/messages/assistant.rb +64 -17
  47. data/lib/riffer/params/any_of.rb +37 -9
  48. data/lib/riffer/params/param.rb +35 -14
  49. data/lib/riffer/params.rb +34 -19
  50. data/lib/riffer/providers/amazon_bedrock.rb +38 -5
  51. data/lib/riffer/providers/anthropic/client.rb +49 -0
  52. data/lib/riffer/providers/anthropic.rb +19 -452
  53. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +219 -0
  54. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +315 -0
  55. data/lib/riffer/providers/anthropic_compatible.rb +5 -0
  56. data/lib/riffer/providers/anthropic_vertex.rb +66 -0
  57. data/lib/riffer/providers/base.rb +19 -13
  58. data/lib/riffer/providers/gemini/client.rb +17 -85
  59. data/lib/riffer/providers/gemini.rb +213 -81
  60. data/lib/riffer/providers/google_cloud/client.rb +106 -0
  61. data/lib/riffer/providers/google_cloud.rb +99 -0
  62. data/lib/riffer/providers/open_ai.rb +21 -16
  63. data/lib/riffer/providers/repository.rb +2 -0
  64. data/lib/riffer/stream_events/server_tool_done.rb +21 -0
  65. data/lib/riffer/testing.rb +6 -0
  66. data/lib/riffer/version.rb +1 -1
  67. data/lib/riffer/wire/sse.rb +51 -0
  68. data/lib/riffer/wire.rb +31 -0
  69. data/lib/riffer.rb +20 -0
  70. data/rbs_collection.lock.yaml +24 -4
  71. data/sig/_private/faraday.rbs +8 -0
  72. data/sig/_private/googleauth.rbs +7 -0
  73. data/sig/generated/riffer/agent/run.rbs +5 -0
  74. data/sig/generated/riffer/agent/session.rbs +6 -0
  75. data/sig/generated/riffer/config/anthropic.rbs +6 -0
  76. data/sig/generated/riffer/config/future.rbs +29 -0
  77. data/sig/generated/riffer/config/gemini.rbs +6 -0
  78. data/sig/generated/riffer/config/google_cloud.rbs +28 -0
  79. data/sig/generated/riffer/config/pricing.rbs +0 -9
  80. data/sig/generated/riffer/config.rbs +10 -0
  81. data/sig/generated/riffer/deprecation/event.rbs +17 -0
  82. data/sig/generated/riffer/deprecation.rbs +27 -0
  83. data/sig/generated/riffer/http/client.rbs +59 -0
  84. data/sig/generated/riffer/http.rbs +4 -0
  85. data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
  86. data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
  87. data/sig/generated/riffer/messages/assistant.rbs +24 -11
  88. data/sig/generated/riffer/params/any_of.rbs +13 -5
  89. data/sig/generated/riffer/params/param.rbs +10 -5
  90. data/sig/generated/riffer/params.rbs +8 -4
  91. data/sig/generated/riffer/providers/amazon_bedrock.rbs +14 -2
  92. data/sig/generated/riffer/providers/anthropic/client.rbs +34 -0
  93. data/sig/generated/riffer/providers/anthropic.rbs +5 -124
  94. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +81 -0
  95. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +108 -0
  96. data/sig/generated/riffer/providers/anthropic_compatible.rbs +4 -0
  97. data/sig/generated/riffer/providers/anthropic_vertex.rbs +45 -0
  98. data/sig/generated/riffer/providers/base.rbs +5 -0
  99. data/sig/generated/riffer/providers/gemini/client.rbs +11 -34
  100. data/sig/generated/riffer/providers/gemini.rbs +66 -4
  101. data/sig/generated/riffer/providers/google_cloud/client.rbs +71 -0
  102. data/sig/generated/riffer/providers/google_cloud.rbs +64 -0
  103. data/sig/generated/riffer/providers/open_ai.rbs +7 -2
  104. data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
  105. data/sig/generated/riffer/testing.rbs +4 -0
  106. data/sig/generated/riffer/wire/sse.rbs +23 -0
  107. data/sig/generated/riffer/wire.rbs +17 -0
  108. data/sig/generated/riffer.rbs +15 -0
  109. data/sig/manual/riffer/deprecation.rbs +5 -0
  110. data/sig/manual/riffer/providers/anthropic_compatible/messages_api.rbs +8 -0
  111. data/sig/manual/riffer/providers/gemini.rbs +8 -0
  112. data/sig/manual/riffer/providers/google_cloud.rbs +8 -0
  113. data/sig/manual/riffer/wire.rbs +5 -0
  114. metadata +76 -5
  115. data/sig/_private/anthropic.rbs +0 -17
  116. data/sig/_private/riffer/providers/anthropic.rbs +0 -6
  117. data/sig/_private/riffer/providers/gemini.rbs +0 -7
@@ -1,107 +1,39 @@
1
1
  # frozen_string_literal: true
2
2
  # rbs_inline: enabled
3
3
 
4
- require "json"
5
- require "net/http"
6
- require "uri"
7
-
8
4
  # <tt>Riffer.config.gemini.client</tt> accepts any object implementing +post+ and +post_stream+
9
- # with these contracts; this class is the default, not a required base.
10
- class Riffer::Providers::Gemini::Client
11
- # @rbs @api_key: String?
5
+ # (see Riffer::HTTP::Client); this class is the default, not a required base.
6
+ class Riffer::Providers::Gemini::Client < Riffer::HTTP::Client
7
+ # @rbs @api_key: String
12
8
  # @rbs @base_url: String
13
- # @rbs @open_timeout: Integer
14
- # @rbs @read_timeout: Integer
15
- # @rbs @write_timeout: Integer?
16
- # @rbs @proxy_address: String?
17
- # @rbs @proxy_port: Integer?
18
9
 
19
10
  DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com" #: String
20
- DEFAULT_OPEN_TIMEOUT = 10 #: Integer
21
- DEFAULT_READ_TIMEOUT = 60 #: Integer
22
-
23
- #: (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
24
- def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, open_timeout: DEFAULT_OPEN_TIMEOUT,
25
- read_timeout: DEFAULT_READ_TIMEOUT, write_timeout: nil,
26
- proxy_address: nil, proxy_port: nil)
27
- @api_key = api_key
28
- @base_url = base_url
29
- @open_timeout = open_timeout
30
- @read_timeout = read_timeout
31
- @write_timeout = write_timeout
32
- @proxy_address = proxy_address
33
- @proxy_port = proxy_port
34
- end
35
-
36
- # Raises Riffer::Error on a non-success status.
37
- #--
38
- #: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
39
- def post(path, body)
40
- uri = URI("#{@base_url}/#{path}")
41
- response = start_http(uri) { |http| http.request(build_request(uri, body)) }
42
- handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
43
- JSON.parse(response.body, symbolize_names: true)
44
- end
45
11
 
46
- # Raises Riffer::Error on a non-success status.
47
12
  #--
48
- #: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
49
- def post_stream(path, body, &block)
50
- uri = URI("#{@base_url}/#{path}")
51
- start_http(uri) do |http|
52
- http.request(build_request(uri, body)) do |response|
53
- handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
54
-
55
- begin
56
- response.read_body(&block)
57
- rescue IOError
58
- # A pre-buffered body (VCR/WebMock playback) raises IOError on a
59
- # streaming read; hand over the full body instead.
60
- yield(response.body)
61
- end
62
- end
63
- end
13
+ #: (api_key: String, ?base_url: String, ?headers: Hash[String, String], ?connection: Faraday::Connection?) -> void
14
+ def initialize(api_key:, base_url: DEFAULT_BASE_URL, headers: {}, connection: nil)
15
+ super(headers: headers, connection: connection)
16
+ @api_key = api_key
17
+ @base_url = base_url.chomp("/")
64
18
  end
65
19
 
66
20
  private
67
21
 
68
22
  #--
69
- #: (URI::Generic, Hash[Symbol, untyped]) -> Net::HTTP::Post
70
- def build_request(uri, body)
71
- request = Net::HTTP::Post.new(uri)
72
- request["Content-Type"] = "application/json"
73
- request["x-goog-api-key"] = @api_key
74
- request.body = body.to_json
75
- request
23
+ #: (String) -> String
24
+ def url_for(path)
25
+ "#{@base_url}/#{path}"
76
26
  end
77
27
 
78
28
  #--
79
- #: [R] (URI::Generic) { (Net::HTTP) -> R } -> R
80
- def start_http(uri, &)
81
- host = uri.hostname #: String
82
- options = {
83
- use_ssl: uri.scheme == "https",
84
- open_timeout: @open_timeout,
85
- read_timeout: @read_timeout,
86
- } #: Hash[Symbol, untyped]
87
- options[:write_timeout] = @write_timeout if @write_timeout
88
-
89
- if @proxy_address
90
- Net::HTTP.start(host, uri.port, @proxy_address, @proxy_port, nil, nil, **options, &)
91
- else
92
- Net::HTTP.start(host, uri.port, **options, &)
93
- end
29
+ #: () -> Hash[String, String]
30
+ def headers
31
+ { "x-goog-api-key" => @api_key }
94
32
  end
95
33
 
96
34
  #--
97
- #: (Net::HTTPResponse) -> void
98
- def handle_api_error!(response)
99
- parsed = begin
100
- JSON.parse(response.body, symbolize_names: true)
101
- rescue JSON::ParserError
102
- { message: response.body }
103
- end
104
- error_message = parsed.dig(:error, :message) || parsed[:message] || response.body
105
- raise Riffer::Error, "Gemini API error (#{response.code}): #{error_message}"
35
+ #: () -> String
36
+ def error_label
37
+ "Gemini"
106
38
  end
107
39
  end
@@ -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,22 +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
- schema[:anyOf] = schema[:anyOf].map { |branch| strip_additional_properties(branch) } if schema[:anyOf]
344
-
345
- schema
346
- end
347
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