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
@@ -12,46 +12,48 @@ Riffer.configure do |config|
12
12
  end
13
13
  ```
14
14
 
15
+ When `config.gemini.api_key` is unset, the provider reads `GEMINI_API_KEY`; with neither set it raises `Riffer::ArgumentError`. Set `config.gemini.base_url` to send requests somewhere other than `https://generativelanguage.googleapis.com` (proxies, regional mirrors).
16
+
15
17
  ## HTTP Client
16
18
 
17
- Gemini has no vendor SDK, so riffer ships its own transport: `Riffer::Providers::Gemini::Client`. The provider builds one from the configured `api_key` by default; construct your own to tune the HTTP knobs and assign it to `config.gemini.client`:
19
+ Gemini has no vendor SDK, so riffer ships its own transport: `Riffer::Providers::Gemini::Client`, built on `Riffer::HTTP::Client`. The provider builds one from the configured credentials by default; construct your own to change timeouts, add retries or route through a proxy, and assign it to `config.gemini.client`:
18
20
 
19
21
  ```ruby
20
22
  Riffer.configure do |config|
21
23
  config.gemini.client = Riffer::Providers::Gemini::Client.new(
22
24
  api_key: ENV['GEMINI_API_KEY'],
23
- read_timeout: 120
25
+ connection: Faraday.new(request: { open_timeout: 10, read_timeout: 120 })
24
26
  )
25
27
  end
26
28
  ```
27
29
 
28
- | Option | Default | Description |
29
- | --------------- | ------------------------------------------- | -------------------------------------- |
30
- | `api_key` | `nil` | Sent as the `x-goog-api-key` header |
31
- | `base_url` | `https://generativelanguage.googleapis.com` | API origin (proxies, regional mirrors) |
32
- | `open_timeout` | `10` | Connection-open timeout in seconds |
33
- | `read_timeout` | `60` | Read timeout in seconds |
34
- | `write_timeout` | `nil` | Write timeout in seconds |
35
- | `proxy_address` | `nil` | HTTP proxy host |
36
- | `proxy_port` | `nil` | HTTP proxy port |
30
+ | Option | Default | Description |
31
+ | ------------ | ------------------------------------------- | -------------------------------------------------------------- |
32
+ | `api_key` | required | Sent as the `x-goog-api-key` header |
33
+ | `base_url` | `https://generativelanguage.googleapis.com` | API origin |
34
+ | `connection` | riffer default: 10s open / 600s read | Your own `Faraday::Connection`; see [Connections][connections] |
35
+
36
+ Timeouts, retries, proxies and errors are covered in [Configuration → Connections][connections].
37
37
 
38
38
  The setting accepts a client instance or a no-argument `Proc`, resolved on every LLM call — see [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
39
39
 
40
- The class is a default implementation, not a required base: any object implementing the two-method contract works, e.g. a Faraday-based or instrumented transport.
40
+ The class is a default implementation, not a required base: any object implementing the two-method contract works, e.g. an instrumented transport.
41
41
 
42
- | Method | Contract |
43
- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
44
- | `post(path, body)` | POST `body` as JSON to `path`; return the parsed response `Hash` (symbol keys); raise `Riffer::Error` on a non-success status |
45
- | `post_stream(path, body) { \|chunk\| }` | POST `body` as JSON to `path`; yield raw response body chunks; raise `Riffer::Error` on a non-success status |
42
+ | Method | Contract |
43
+ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
44
+ | `post(path, body)` | POST `body` as JSON to `path`; return the parsed response `Hash` (symbol keys); raise `Riffer::APIError` on a non-success status |
45
+ | `post_stream(path, body) { \|chunk\| }` | POST `body` as JSON to `path`; yield raw response body chunks; raise `Riffer::APIError` on a non-success status |
46
+
47
+ [connections]: ../CONFIGURATION.md#connections
46
48
 
47
49
  ## Supported Models
48
50
 
49
51
  Use Gemini model IDs in the `gemini/model` format:
50
52
 
51
53
  ```ruby
52
- model 'gemini/gemini-2.5-flash-lite'
53
- model 'gemini/gemini-2.5-pro'
54
- model 'gemini/gemini-2.5-flash'
54
+ model 'gemini/gemini-3.5-flash-lite'
55
+ model 'gemini/gemini-3.8-flash'
56
+ model 'gemini/gemini-3.1-pro-preview'
55
57
  ```
56
58
 
57
59
  ## Model Options
@@ -90,6 +92,15 @@ model_options thinkingConfig: {thinkingLevel: "low"}
90
92
 
91
93
  The agent-level [`reasoning`](../AGENTS.md#reasoning) setting writes `thinkingConfig: {thinkingLevel: "<level>"}` by default, including `"off"` for `:off`, which Gemini rejects. Gemini 2.5 models take `thinkingBudget` instead; map them in a [catalog](../CATALOG.md#reasoning) entry.
92
94
 
95
+ ### web_search
96
+
97
+ Enable grounding with Google Search. Pass `true` to use defaults or a hash to merge into the `googleSearch` tool:
98
+
99
+ ```ruby
100
+ model_options web_search: true
101
+ model_options web_search: {timeRangeFilter: {startTime: "2026-01-01T00:00:00Z", endTime: "2026-06-30T00:00:00Z"}}
102
+ ```
103
+
93
104
  ## Usage
94
105
 
95
106
  ### Basic Generation
@@ -99,7 +110,7 @@ provider = Riffer::Providers::Gemini.new
99
110
 
100
111
  response = provider.generate_text(
101
112
  prompt: "Hello!",
102
- model: "gemini-2.5-flash-lite"
113
+ model: "gemini-3.5-flash-lite"
103
114
  )
104
115
  puts response.content
105
116
  ```
@@ -107,7 +118,7 @@ puts response.content
107
118
  ### Streaming
108
119
 
109
120
  ```ruby
110
- provider.stream_text(prompt: "Tell me a story", model: "gemini-2.5-flash-lite").each do |event|
121
+ provider.stream_text(prompt: "Tell me a story", model: "gemini-3.5-flash-lite").each do |event|
111
122
  case event
112
123
  when Riffer::StreamEvents::TextDelta
113
124
  print event.content
@@ -127,12 +138,16 @@ structured_output = Riffer::Agent::StructuredOutput.new(params)
127
138
 
128
139
  response = provider.generate_text(
129
140
  prompt: "Analyze: 'This is great!'",
130
- model: "gemini-2.5-flash-lite",
141
+ model: "gemini-3.5-flash-lite",
131
142
  structured_output: structured_output
132
143
  )
133
144
  puts response.structured_output
134
145
  ```
135
146
 
147
+ Structured output is sent as `responseFormat`, which needs a gemini-3 model or later. gemini-2.x models ignore it and return prose.
148
+
149
+ The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up. A `Hash` param needs a block and an `Array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
150
+
136
151
  ### Tool Calling
137
152
 
138
153
  ```ruby
@@ -148,11 +163,48 @@ end
148
163
 
149
164
  response = provider.generate_text(
150
165
  prompt: "What's the weather in Tokyo?",
151
- model: "gemini-2.5-flash-lite",
166
+ model: "gemini-3.5-flash-lite",
152
167
  tools: [WeatherTool]
153
168
  )
154
169
  ```
155
170
 
171
+ Gemini's own call ids are short, so riffer gives each tool call its own `call_id` (`gemini_call_<hex>`) and appends Gemini's id when there is one. On later turns riffer sends that id back on the function call and its result, so Gemini can match results to parallel calls of the same tool.
172
+
173
+ ### Thought Signatures
174
+
175
+ Gemini 3 models attach an opaque `thoughtSignature` to the first function call of each step, and to the last text part of an answer. A later request that sends a function call back without its signature is rejected with a 400.
176
+
177
+ Riffer keeps each signature on the assistant message as the `data` of an `:encrypted` [reasoning part](../MESSAGES.md#reasoning) tagged `format: "gemini-generate-content-v1"` (`Riffer::Providers::Gemini::REASONING_FORMAT`). A signature from a function call carries that tool call's `call_id` as its `id`; the text signature has no `id`. Streams emit them as `ReasoningDone` events. On later turns riffer puts each signature back on the part it came from. You don't have to do anything as long as the assistant messages stay in the history.
178
+
179
+ A function call that Gemini didn't sign, such as one another provider made before the conversation switched to Gemini, goes out with Gemini's placeholder signature (`skip_thought_signature_validator`), which Gemini accepts in place of a real one. That covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the reasoning when you store messages.
180
+
181
+ ### Web Search
182
+
183
+ With `web_search` set, riffer adds the `googleSearch` tool and turns on `toolConfig.includeServerSideToolInvocations`, which Gemini requires when Google Search and function tools are used together.
184
+
185
+ ```ruby
186
+ provider.stream_text(
187
+ prompt: "What is the latest Ruby version?",
188
+ model: "gemini-3.5-flash-lite",
189
+ web_search: true
190
+ ).each do |event|
191
+ case event
192
+ when Riffer::StreamEvents::WebSearchStatus
193
+ puts "[search: #{event.status}] #{event.query}"
194
+ when Riffer::StreamEvents::WebSearchDone
195
+ puts "[search complete: #{event.query}]"
196
+ event.sources.each { |s| puts " - #{s[:title]}: #{s[:url]}" }
197
+ when Riffer::StreamEvents::TextDelta
198
+ print event.content
199
+ end
200
+ end
201
+ ```
202
+
203
+ - Each search query streams as a `"searching"` `WebSearchStatus`; a `"completed"` status follows once the results are in.
204
+ - Gemini reports the queries and sources of a response together, at the end, without saying which query found which source. Riffer emits them as one `WebSearchDone`, after the text, with the queries joined by `", "`.
205
+ - Source `title`s are domains (`"ruby-lang.org"`) and `url`s are Google redirect links (`https://vertexaisearch.cloud.google.com/grounding-api-redirect/...`).
206
+ - The search parts of a response aren't sent back on later turns. After a tool call, Gemini searches again if it still needs results.
207
+
156
208
  ### File Support
157
209
 
158
210
  Gemini's API only accepts inline base64-encoded files (images and documents), never a URL reference:
@@ -161,7 +213,7 @@ Gemini's API only accepts inline base64-encoded files (images and documents), ne
161
213
  file = Riffer::Messages::User::FilePart.new(data: base64_data, media_type: "image/png")
162
214
  response = provider.generate_text(
163
215
  prompt: "Describe this image",
164
- model: "gemini-2.5-flash-lite",
216
+ model: "gemini-3.5-flash-lite",
165
217
  files: [file]
166
218
  )
167
219
  ```
@@ -170,6 +222,4 @@ A `FilePart.from_url` source works too — riffer downloads and base64-encodes i
170
222
 
171
223
  ## Limitations
172
224
 
173
- - **No web search** - Gemini's standard API does not include a web search tool
174
225
  - **Tool call IDs** - Gemini does not return unique call IDs for tool invocations; IDs are generated client-side
175
- - **String enums only** - Gemini rejects non-string `enum` values, including on `Array, of:` items
@@ -0,0 +1,363 @@
1
+ # Google Cloud Providers
2
+
3
+ Two providers connect to models hosted on Gemini Enterprise Agent Platform (formerly Vertex AI), authenticating with Google Cloud credentials instead of an API key:
4
+
5
+ | Provider | Identifier | Models |
6
+ | ------------------------------------ | ------------------ | ------ |
7
+ | `Riffer::Providers::GoogleCloud` | `google_cloud` | Gemini |
8
+ | `Riffer::Providers::AnthropicVertex` | `anthropic_vertex` | Claude |
9
+
10
+ Both read `config.google_cloud` and send requests through the same client, `Riffer::Providers::GoogleCloud::Client`.
11
+
12
+ ## Installation
13
+
14
+ Add the `googleauth` gem to your Gemfile:
15
+
16
+ ```ruby
17
+ gem 'googleauth'
18
+ ```
19
+
20
+ ## Configuration
21
+
22
+ ```ruby
23
+ Riffer.configure do |config|
24
+ config.google_cloud.project_id = 'my-project'
25
+ config.google_cloud.location = 'us-central1' # Optional, defaults to "global"
26
+ end
27
+ ```
28
+
29
+ | Setting | Default | Description |
30
+ | ------------- | --------------------------------------- | -------------------------------------------------------------------------------- |
31
+ | `project_id` | `nil` (required) | The Google Cloud project that owns the Agent Platform quota and billing |
32
+ | `location` | `"global"` | The Agent Platform location requests are sent to; picks the endpoint (see below) |
33
+ | `credentials` | `nil` (Application Default Credentials) | A `googleauth` credentials object |
34
+ | `client` | `nil` | A client instance or no-argument `Proc` (see [HTTP Client](#http-client)) |
35
+
36
+ `project_id` and `location` accept a `String` or `nil` and raise `Riffer::ArgumentError` naming the setting for anything else. Setting `location` to `nil` restores `"global"`. Without a `project_id` (and no `client`), the first request raises `Riffer::ArgumentError`.
37
+
38
+ ### Credentials
39
+
40
+ With `credentials` unset, riffer uses [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials). `googleauth` checks, in order:
41
+
42
+ 1. The service account key file named by `GOOGLE_APPLICATION_CREDENTIALS`.
43
+ 2. Your own Google account, after you run `gcloud auth application-default login` (local development).
44
+ 3. The service account attached to the machine on Compute Engine, Cloud Run, or GKE.
45
+
46
+ To use a specific identity, pass any `googleauth` credentials object:
47
+
48
+ ```ruby
49
+ Riffer.configure do |config|
50
+ config.google_cloud.project_id = 'my-project'
51
+ config.google_cloud.credentials = Google::Auth::ServiceAccountCredentials.make_creds(
52
+ json_key_io: File.open(ENV.fetch('GOOGLE_CLOUD_SERVICE_ACCOUNT_KEY')),
53
+ scope: Riffer::Providers::GoogleCloud::Client::SCOPE
54
+ )
55
+ end
56
+ ```
57
+
58
+ Riffer caches the access token and refreshes it shortly before it expires.
59
+
60
+ ## Locations and Data Residency
61
+
62
+ The location decides the endpoint a request is sent to:
63
+
64
+ | `location` | Endpoint |
65
+ | ------------------------------ | ----------------------------------------------- |
66
+ | `global` | `https://aiplatform.googleapis.com` |
67
+ | `us`, `eu` (multi-region) | `https://aiplatform.{us,eu}.rep.googleapis.com` |
68
+ | Any region, e.g. `us-central1` | `https://{location}-aiplatform.googleapis.com` |
69
+
70
+ **The default `"global"` location offers no data-residency guarantee.** Google may serve a global request from any region. If your data must stay in a region or jurisdiction, set an explicit regional or multi-region `location`, and check that the model you use is available there.
71
+
72
+ A single `location` applies to every `google_cloud/...` and `anthropic_vertex/...` model. To bind one location explicitly, or to reach several locations from one process, use either approach below.
73
+
74
+ ### Binding the client
75
+
76
+ `config.google_cloud.client` takes a client instance or a no-argument `Proc` resolved on every LLM call (see [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients)). Both providers use it, and it wins over `project_id`, `location`, and `credentials`:
77
+
78
+ ```ruby
79
+ Riffer.configure do |config|
80
+ config.google_cloud.client = Riffer::Providers::GoogleCloud::Client.new(
81
+ project_id: 'my-project',
82
+ location: 'europe-west4'
83
+ )
84
+ end
85
+ ```
86
+
87
+ ### One provider per location
88
+
89
+ To route different agents to different locations, register a provider subclass per location. Riffer constructs providers with no arguments, so the location lives on the class:
90
+
91
+ ```ruby
92
+ class GoogleCloudEurope < Riffer::Providers::GoogleCloud
93
+ private
94
+
95
+ # Ignore config.google_cloud.client, so this class always uses its own location.
96
+ def global_client = nil
97
+
98
+ def build_client
99
+ Riffer::Providers::GoogleCloud::Client.new(
100
+ project_id: Riffer.config.google_cloud.project_id,
101
+ location: 'europe-west4',
102
+ credentials: Riffer.config.google_cloud.credentials
103
+ )
104
+ end
105
+ end
106
+
107
+ Riffer::Providers::Repository.register(:google_cloud_eu) { GoogleCloudEurope }
108
+ ```
109
+
110
+ A subclass of `Riffer::Providers::AnthropicVertex` binds a location for Claude models the same way.
111
+
112
+ Agents then pick the location by model prefix (`model 'google_cloud_eu/gemini-3.5-flash-lite'`). Register each subclass once, at boot, and return the same class from the block every time: riffer maps a provider class back to its registry key, and the [catalog](../CATALOG.md) looks up pricing and reasoning entries under that key (`google_cloud_eu/gemini-3.5-flash-lite`).
113
+
114
+ ## HTTP Client
115
+
116
+ Riffer ships its own Agent Platform transport, `Riffer::Providers::GoogleCloud::Client`, built on `Riffer::HTTP::Client`. The provider builds one from the configured settings by default.
117
+
118
+ | Option | Default | Description |
119
+ | ------------- | -------------------------------------- | -------------------------------------------------------------- |
120
+ | `project_id` | required | Project segment of the resource path |
121
+ | `location` | required | Location segment of the resource path; also picks the endpoint |
122
+ | `credentials` | `nil` | A `googleauth` credentials object; `nil` resolves ADC |
123
+ | `base_url` | derived from `location` | API origin (Private Service Connect, proxies) |
124
+ | `headers` | `{}` | Sent on every request; replaces riffer's same-name headers |
125
+ | `connection` | Faraday defaults, 10s open / 600s read | Your own `Faraday::Connection`; see [Connections][connections] |
126
+
127
+ Timeouts, retries, proxies and errors are covered in [Configuration → Connections][connections]. Errors are labelled `Google Cloud API error (<status>): <message>`.
128
+
129
+ The class is a default implementation, not a required base: any object implementing the two-method contract works. Paths are relative to `v1/projects/{project_id}/locations/{location}/`.
130
+
131
+ | Method | Contract |
132
+ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
133
+ | `post(path, body)` | POST `body` as JSON to `path`; return the parsed response `Hash` (symbol keys); raise `Riffer::APIError` on a non-success status |
134
+ | `post_stream(path, body) { \|chunk\| }` | POST `body` as JSON to `path`; yield raw response body chunks; raise `Riffer::APIError` on a non-success status |
135
+
136
+ [connections]: ../CONFIGURATION.md#connections
137
+
138
+ ## Supported Models
139
+
140
+ Use Agent Platform model IDs, prefixed with the provider for the model family:
141
+
142
+ ```ruby
143
+ model 'google_cloud/gemini-3.5-flash-lite'
144
+ model 'google_cloud/gemini-3.8-flash'
145
+ model 'anthropic_vertex/claude-haiku-5-5'
146
+ model 'anthropic_vertex/claude-haiku-4-5@20251001'
147
+ ```
148
+
149
+ Model IDs may carry an `@version` suffix, as Agent Platform's dated Claude snapshots do; use the ID Model Garden shows.
150
+
151
+ ## Gemini Models (`google_cloud`)
152
+
153
+ ### Model Options
154
+
155
+ #### temperature
156
+
157
+ Controls randomness:
158
+
159
+ ```ruby
160
+ model_options temperature: 0.7
161
+ ```
162
+
163
+ #### maxOutputTokens
164
+
165
+ Maximum tokens in response:
166
+
167
+ ```ruby
168
+ model_options maxOutputTokens: 4096
169
+ ```
170
+
171
+ #### topP
172
+
173
+ Nucleus sampling:
174
+
175
+ ```ruby
176
+ model_options topP: 0.9
177
+ ```
178
+
179
+ #### thinkingConfig
180
+
181
+ Controls thinking, passed through as Agent Platform expects:
182
+
183
+ ```ruby
184
+ model_options thinkingConfig: {thinkingLevel: "low"}
185
+ ```
186
+
187
+ The agent-level [`reasoning`](../AGENTS.md#reasoning) setting writes `thinkingConfig: {thinkingLevel: "<level>"}` by default. To map a model differently, add a [catalog](../CATALOG.md#reasoning) entry under its `google_cloud/...` key.
188
+
189
+ #### web_search
190
+
191
+ Enable grounding with Google Search. Pass `true` to use defaults or a hash to merge into the `googleSearch` tool:
192
+
193
+ ```ruby
194
+ model_options web_search: true
195
+ model_options web_search: {excludeDomains: ["example.com"]}
196
+ ```
197
+
198
+ ### Basic Generation
199
+
200
+ ```ruby
201
+ provider = Riffer::Providers::GoogleCloud.new
202
+
203
+ response = provider.generate_text(
204
+ prompt: "Hello!",
205
+ model: "gemini-3.5-flash-lite"
206
+ )
207
+ puts response.content
208
+ ```
209
+
210
+ ### Streaming
211
+
212
+ ```ruby
213
+ provider.stream_text(prompt: "Tell me a story", model: "gemini-3.5-flash-lite").each do |event|
214
+ case event
215
+ when Riffer::StreamEvents::TextDelta
216
+ print event.content
217
+ when Riffer::StreamEvents::TextDone
218
+ puts "\n---"
219
+ end
220
+ end
221
+ ```
222
+
223
+ ### Structured Output
224
+
225
+ ```ruby
226
+ params = Riffer::Params.new
227
+ params.required(:sentiment, String)
228
+ params.required(:score, Float)
229
+ structured_output = Riffer::Agent::StructuredOutput.new(params)
230
+
231
+ response = provider.generate_text(
232
+ prompt: "Analyze: 'This is great!'",
233
+ model: "gemini-3.5-flash-lite",
234
+ structured_output: structured_output
235
+ )
236
+ puts response.structured_output
237
+ ```
238
+
239
+ The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up. A `Hash` param needs a block and an `Array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
240
+
241
+ ### Tool Calling
242
+
243
+ ```ruby
244
+ class WeatherTool < Riffer::Tool
245
+ description "Gets weather"
246
+ params do
247
+ required :city, String
248
+ end
249
+ def call(context:, city:)
250
+ text("Sunny in #{city}")
251
+ end
252
+ end
253
+
254
+ response = provider.generate_text(
255
+ prompt: "What's the weather in Tokyo?",
256
+ model: "gemini-3.5-flash-lite",
257
+ tools: [WeatherTool]
258
+ )
259
+ ```
260
+
261
+ Riffer gives each tool call its own `call_id` (`gemini_call_<hex>`) and appends the model's id when there is one. On later turns riffer sends that id back on the function call and its result, so the model can match results to parallel calls of the same tool.
262
+
263
+ ### Thought Signatures
264
+
265
+ Gemini 3 models attach an opaque `thoughtSignature` to the first function call of each step, and to the last text part of an answer. A later request that sends a function call back without its signature is rejected with a 400.
266
+
267
+ Riffer keeps each signature on the assistant message as the `data` of an `:encrypted` [reasoning part](../MESSAGES.md#reasoning) tagged `format: "google-cloud-generate-content-v1"` (`Riffer::Providers::GoogleCloud::REASONING_FORMAT`). A signature from a function call carries that tool call's `call_id` as its `id`; the text signature has no `id`. Streams emit them as `ReasoningDone` events. On later turns riffer puts each signature back on the part it came from. You don't have to do anything as long as the assistant messages stay in the history.
268
+
269
+ A function call without an Agent Platform signature goes out with Google's placeholder signature (`skip_thought_signature_validator`), which Agent Platform accepts in place of a real one. That happens when the call came from another provider, or from the Gemini Developer API, whose signatures Agent Platform rejects. It covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the reasoning when you store messages.
270
+
271
+ ### Web Search
272
+
273
+ With `web_search` set, riffer adds the `googleSearch` tool and turns on `toolConfig.includeServerSideToolInvocations`, which is required when Google Search and function tools are used together.
274
+
275
+ ```ruby
276
+ provider.stream_text(
277
+ prompt: "What is the latest Ruby version?",
278
+ model: "gemini-3.5-flash-lite",
279
+ web_search: true
280
+ ).each do |event|
281
+ case event
282
+ when Riffer::StreamEvents::WebSearchDone
283
+ puts "[search complete: #{event.query}]"
284
+ event.sources.each { |s| puts " - #{s[:title]}: #{s[:url]}" }
285
+ when Riffer::StreamEvents::TextDelta
286
+ print event.content
287
+ end
288
+ end
289
+ ```
290
+
291
+ - No `WebSearchStatus` events are streamed. The queries and sources of a response arrive together, at the end, without saying which query found which source. Riffer emits them as one `WebSearchDone`, after the text, with the queries joined by `", "`.
292
+ - Source `title`s are domains (`"ruby-lang.org"`) and `url`s are Google redirect links (`https://vertexaisearch.cloud.google.com/grounding-api-redirect/...`).
293
+ - After a tool call, the model searches again if it still needs results.
294
+
295
+ ### File Support
296
+
297
+ Files are sent inline as base64 (images and documents):
298
+
299
+ ```ruby
300
+ file = Riffer::Messages::User::FilePart.new(data: base64_data, media_type: "image/png")
301
+ response = provider.generate_text(
302
+ prompt: "Describe this image",
303
+ model: "gemini-3.5-flash-lite",
304
+ files: [file]
305
+ )
306
+ ```
307
+
308
+ A `FilePart.from_url` source works too: riffer downloads and base64-encodes it before sending, subject to the `allow_downloads` policy in [File Downloads](../CONFIGURATION.md#file-downloads).
309
+
310
+ ### Tags
311
+
312
+ Per-call [tags](../AGENTS.md#per-call-tags) are sent as request `labels`, which show up in Google Cloud billing reports. Riffer rewrites each tag into a valid label: downcased, any character other than a letter, digit, `_` or `-` replaced with `_`, and cut to 63 characters. Tags whose key doesn't start with a letter are dropped. `agent: "support/triage_agent"` goes out as `agent: "support_triage_agent"`.
313
+
314
+ To send fixed labels, set them as a model option; tags are merged over them:
315
+
316
+ ```ruby
317
+ model_options labels: {cost_center: "cc_1234"}
318
+ ```
319
+
320
+ ## Claude Models (`anthropic_vertex`)
321
+
322
+ Claude models use Agent Platform's Anthropic endpoints (`rawPredict` and `streamRawPredict`), which take the Anthropic Messages API body. Riffer builds the same body as the [Anthropic provider](ANTHROPIC.md), so the same [model options](ANTHROPIC.md#model-options) apply (`max_tokens`, defaulting to `4096`, `thinking`, `output_config`, `web_search`, ...). The model goes in the URL, and `anthropic_version: "2026-10-21"`, the Anthropic provider's API version, goes in the body in place of the `anthropic-version` header. That version rejects `temperature`, `top_p` and `top_k`. Enable each Claude model for your project in Model Garden before calling it.
323
+
324
+ To send another version, subclass the provider, override `anthropic_version`, and register the subclass under `anthropic_vertex`. A registration replaces the built-in under the same identifier, so models and [catalog](../CATALOG.md) entries keep their `anthropic_vertex/...` names:
325
+
326
+ ```ruby
327
+ class LegacyAnthropicVertex < Riffer::Providers::AnthropicVertex
328
+ private
329
+
330
+ def anthropic_version = "vertex-2023-10-16"
331
+ end
332
+
333
+ Riffer::Providers::Repository.register(:anthropic_vertex) { LegacyAnthropicVertex }
334
+ ```
335
+
336
+ ```ruby
337
+ provider = Riffer::Providers::AnthropicVertex.new
338
+
339
+ response = provider.generate_text(
340
+ prompt: "Hello!",
341
+ model: "claude-haiku-5-5",
342
+ thinking: { type: "adaptive", display: "summarized" },
343
+ output_config: { effort: "high" }
344
+ )
345
+ ```
346
+
347
+ Claude models on Agent Platform behave as they do on the Anthropic provider:
348
+
349
+ - **Reasoning** is captured as [reasoning parts](../MESSAGES.md#reasoning) tagged `format: "anthropic-messages-v1"` and sent back on later turns, as described in [Anthropic → Reasoning Replay](ANTHROPIC.md#reasoning-replay). Thinking signatures are accepted by both APIs, so a conversation can move between `anthropic` and `anthropic_vertex`. The agent-level [`reasoning`](../AGENTS.md#reasoning) setting uses the Anthropic default; [catalog](../CATALOG.md#reasoning) entries go under `anthropic_vertex/...` keys.
350
+ - **Web search:** `web_search: true` (or a hash of options) adds the `web_search_20250305` server tool and streams `WebSearchStatus` / `WebSearchDone` events.
351
+ - **Structured output** is sent as a strict `output_config.format` JSON schema.
352
+ - **Skills** are rendered with the XML skills adapter.
353
+ - **Tags:** only the reserved `user_id` tag is sent, as `metadata.user_id`.
354
+ - **Incomplete streams:** a stream that ends without a `message_stop` event raises `Riffer::IncompleteStreamError`.
355
+
356
+ `anthropic_vertex` never reads `config.anthropic` or `ANTHROPIC_API_KEY`. Files are sent inline as base64.
357
+
358
+ Web search and structured output are partner-model features that an organization policy can turn off. If a request fails with a `constraints/vertexai.allowedPartnerModelFeatures` violation, an organization policy administrator must allow `publishers/anthropic/models/MODEL:web_search` or `:structured_outputs` (or `publishers/anthropic` for every feature); see [Control access to Model Garden models](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/control-model-access).
359
+
360
+ ## Limitations
361
+
362
+ - **No `gs://` file references** - files are always sent inline
363
+ - **Tool call IDs** - Gemini does not return unique call IDs for tool invocations; IDs are generated client-side
@@ -96,6 +96,8 @@ provider.calls
96
96
  expect(provider.calls.last[:messages].last[:content]).to eq("Hi")
97
97
  ```
98
98
 
99
+ Each message is recorded as its `to_h`, so an assistant message has `parts` rather than `content` (see [Messages — Parts](../MESSAGES.md#parts)).
100
+
99
101
  ## Clearing State
100
102
 
101
103
  Reset stubbed responses:
@@ -96,7 +96,7 @@ Each `reasoning` item in a Responses API output becomes [reasoning parts](../MES
96
96
 
97
97
  The `:encrypted` part is always present, even when the response carried no `encrypted_content`, so the item's `id` is kept. When streaming, the parts are yielded as `ReasoningDone` events once the item completes; summary text still arrives as `ReasoningDelta` events before that.
98
98
 
99
- On the next request, parts sharing an `id` go back as one `reasoning` item, ahead of the assistant's text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don't have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the `reasoning` key when you store them.
99
+ On the next request, parts sharing an `id` go back as one `reasoning` item, ahead of the assistant's text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don't have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the reasoning when you store them.
100
100
 
101
101
  With `store` left on (the API default), OpenAI can resolve a replayed item from its `id` alone. With `model_options store: false`, the item can only be replayed from its encrypted payload, so request it explicitly:
102
102
 
@@ -118,6 +118,8 @@ model_options web_search: true
118
118
  model_options web_search: {search_context_size: "medium"}
119
119
  ```
120
120
 
121
+ With web search on, riffer also adds `"web_search_call.action.sources"` to the request's `include`, keeping any entries you pass, so `WebSearchDone` carries the sources OpenAI searched.
122
+
121
123
  ## Example
122
124
 
123
125
  ```ruby
@@ -4,15 +4,17 @@ Providers are adapters that connect Riffer to LLM services. They implement a com
4
4
 
5
5
  ## Available Providers
6
6
 
7
- | Provider | Identifier | Gem Required |
8
- | -------------- | ---------------- | ------------------------ |
9
- | OpenAI | `openai` | `openai` |
10
- | Azure OpenAI | `azure_openai` | `openai` |
11
- | Amazon Bedrock | `amazon_bedrock` | `aws-sdk-bedrockruntime` |
12
- | Anthropic | `anthropic` | `anthropic` |
13
- | Gemini | `gemini` | None |
14
- | OpenRouter | `openrouter` | `openai` |
15
- | Mock | `mock` | None |
7
+ | Provider | Identifier | Gem Required |
8
+ | --------------------- | ------------------ | ------------------------ |
9
+ | OpenAI | `openai` | `openai` |
10
+ | Azure OpenAI | `azure_openai` | `openai` |
11
+ | Amazon Bedrock | `amazon_bedrock` | `aws-sdk-bedrockruntime` |
12
+ | Anthropic | `anthropic` | None |
13
+ | Gemini | `gemini` | None |
14
+ | Google Cloud (Gemini) | `google_cloud` | `googleauth` |
15
+ | Google Cloud (Claude) | `anthropic_vertex` | `googleauth` |
16
+ | OpenRouter | `openrouter` | `openai` |
17
+ | Mock | `mock` | None |
16
18
 
17
19
  ## Model String Format
18
20
 
@@ -24,7 +26,9 @@ class MyAgent < Riffer::Agent
24
26
  model 'azure_openai/gpt-5-mini' # Azure OpenAI
25
27
  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0' # Bedrock
26
28
  model 'anthropic/claude-haiku-4-5-20251001' # Anthropic
27
- model 'gemini/gemini-2.5-flash-lite' # Gemini
29
+ model 'gemini/gemini-3.5-flash-lite' # Gemini
30
+ model 'google_cloud/gemini-3.5-flash-lite' # Google Cloud (Gemini)
31
+ model 'anthropic_vertex/claude-haiku-5-5' # Google Cloud (Claude)
28
32
  model 'openrouter/anthropic/claude-sonnet-4.6' # OpenRouter
29
33
  model 'mock/any' # Mock provider
30
34
  end
@@ -34,14 +38,15 @@ end
34
38
 
35
39
  Every credential comes from configuration: `Riffer::Providers::OpenAI.new` takes no arguments.
36
40
 
37
- | Provider | Configured credentials |
38
- | -------------- | ----------------------------------------------------------------- |
39
- | OpenAI | `config.openai.api_key`, `config.openai.base_url` |
40
- | Azure OpenAI | `config.azure_openai.api_key`, `config.azure_openai.endpoint` |
41
- | Anthropic | `config.anthropic.api_key` |
42
- | Amazon Bedrock | `config.amazon_bedrock.api_token`, `config.amazon_bedrock.region` |
43
- | Gemini | `config.gemini.api_key` |
44
- | OpenRouter | `config.openrouter.api_key` |
41
+ | Provider | Configured credentials |
42
+ | ------------------------------ | ----------------------------------------------------------------- |
43
+ | OpenAI | `config.openai.api_key`, `config.openai.base_url` |
44
+ | Azure OpenAI | `config.azure_openai.api_key`, `config.azure_openai.endpoint` |
45
+ | Anthropic | `config.anthropic.api_key`, `config.anthropic.base_url` |
46
+ | Amazon Bedrock | `config.amazon_bedrock.api_token`, `config.amazon_bedrock.region` |
47
+ | Gemini | `config.gemini.api_key`, `config.gemini.base_url` |
48
+ | Google Cloud (Gemini, Claude) | `config.google_cloud.project_id`, `.location`, `.credentials` |
49
+ | OpenRouter | `config.openrouter.api_key` |
45
50
 
46
51
  Out of the box, each provider builds an SDK client from these credentials. Everything else — timeouts, retries, proxies, custom auth — is configured by assigning your own client (an instance, or a `Proc` resolved on every LLM call) to `Riffer.config.<provider>.client`. See [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
47
52
 
@@ -182,6 +187,12 @@ Riffer::Providers::Repository.find(:anthropic)
182
187
  Riffer::Providers::Repository.find(:gemini)
183
188
  # => Riffer::Providers::Gemini
184
189
 
190
+ Riffer::Providers::Repository.find(:google_cloud)
191
+ # => Riffer::Providers::GoogleCloud
192
+
193
+ Riffer::Providers::Repository.find(:anthropic_vertex)
194
+ # => Riffer::Providers::AnthropicVertex
195
+
185
196
  Riffer::Providers::Repository.find(:openrouter)
186
197
  # => Riffer::Providers::OpenRouter
187
198
 
@@ -198,4 +209,5 @@ Riffer::Providers::Repository.find(:mock)
198
209
  - [Mock](MOCK_PROVIDER.md) - Mock provider for testing
199
210
  - [Custom Providers](CUSTOM_PROVIDERS.md) - Creating your own provider
200
211
  - [Gemini](GEMINI.md) - Gemini models via Google GenAI API
212
+ - [Google Cloud](GOOGLE_CLOUD.md) - Gemini and Claude models on Agent Platform (formerly Vertex AI)
201
213
  - [OpenRouter](OPENROUTER.md) - Unified gateway across many vendors