riffer 0.54.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.
- checksums.yaml +4 -4
- data/.claude/rules/rbs-inline.md +6 -6
- data/.release-please-manifest.json +1 -1
- data/.ruby-version +1 -1
- data/CHANGELOG.md +28 -0
- data/README.md +24 -0
- data/Steepfile +2 -2
- data/docs/AGENTS.md +37 -12
- data/docs/CATALOG.md +8 -8
- data/docs/CONFIGURATION.md +47 -16
- data/docs/MCP.md +3 -4
- data/docs/STREAM_EVENTS.md +1 -1
- data/docs/TOOLS.md +11 -11
- data/docs/TRACING.md +1 -1
- data/docs/providers/AMAZON_BEDROCK.md +2 -0
- data/docs/providers/ANTHROPIC.md +32 -36
- data/docs/providers/CUSTOM_PROVIDERS.md +35 -0
- data/docs/providers/GEMINI.md +76 -26
- data/docs/providers/GOOGLE_CLOUD.md +363 -0
- data/docs/providers/PROVIDERS.md +30 -18
- data/docs-site/manifest.yml +3 -0
- data/lib/riffer/agent/structured_output.rb +6 -1
- data/lib/riffer/config/anthropic.rb +9 -0
- data/lib/riffer/config/gemini.rb +9 -0
- data/lib/riffer/config/google_cloud.rb +38 -0
- data/lib/riffer/config.rb +3 -0
- data/lib/riffer/http/client.rb +141 -0
- data/lib/riffer/http.rb +5 -0
- data/lib/riffer/mcp/client.rb +0 -1
- data/lib/riffer/params/any_of.rb +37 -9
- data/lib/riffer/params/param.rb +35 -14
- data/lib/riffer/params.rb +34 -19
- data/lib/riffer/providers/amazon_bedrock.rb +38 -5
- data/lib/riffer/providers/anthropic/client.rb +49 -0
- data/lib/riffer/providers/anthropic.rb +19 -452
- data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +195 -0
- data/lib/riffer/providers/anthropic_compatible/messages_api.rb +293 -0
- data/lib/riffer/providers/anthropic_compatible.rb +5 -0
- data/lib/riffer/providers/anthropic_vertex.rb +66 -0
- data/lib/riffer/providers/base.rb +4 -7
- data/lib/riffer/providers/gemini/client.rb +17 -85
- data/lib/riffer/providers/gemini.rb +213 -81
- data/lib/riffer/providers/google_cloud/client.rb +106 -0
- data/lib/riffer/providers/google_cloud.rb +99 -0
- data/lib/riffer/providers/repository.rb +2 -0
- data/lib/riffer/version.rb +1 -1
- data/lib/riffer/wire/sse.rb +51 -0
- data/lib/riffer/wire.rb +31 -0
- data/lib/riffer.rb +18 -0
- data/rbs_collection.lock.yaml +24 -4
- data/sig/_private/faraday.rbs +8 -0
- data/sig/_private/googleauth.rbs +7 -0
- data/sig/generated/riffer/config/anthropic.rbs +6 -0
- data/sig/generated/riffer/config/gemini.rbs +6 -0
- data/sig/generated/riffer/config/google_cloud.rbs +28 -0
- data/sig/generated/riffer/config.rbs +2 -0
- data/sig/generated/riffer/http/client.rbs +59 -0
- data/sig/generated/riffer/http.rbs +4 -0
- data/sig/generated/riffer/params/any_of.rbs +13 -5
- data/sig/generated/riffer/params/param.rbs +10 -5
- data/sig/generated/riffer/params.rbs +8 -4
- data/sig/generated/riffer/providers/amazon_bedrock.rbs +14 -2
- data/sig/generated/riffer/providers/anthropic/client.rbs +34 -0
- data/sig/generated/riffer/providers/anthropic.rbs +5 -124
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +71 -0
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +99 -0
- data/sig/generated/riffer/providers/anthropic_compatible.rbs +4 -0
- data/sig/generated/riffer/providers/anthropic_vertex.rbs +45 -0
- data/sig/generated/riffer/providers/gemini/client.rbs +11 -34
- data/sig/generated/riffer/providers/gemini.rbs +66 -4
- data/sig/generated/riffer/providers/google_cloud/client.rbs +71 -0
- data/sig/generated/riffer/providers/google_cloud.rbs +64 -0
- data/sig/generated/riffer/wire/sse.rbs +23 -0
- data/sig/generated/riffer/wire.rbs +17 -0
- data/sig/generated/riffer.rbs +12 -0
- data/sig/manual/riffer/providers/anthropic_compatible/messages_api.rbs +8 -0
- data/sig/manual/riffer/providers/gemini.rbs +8 -0
- data/sig/manual/riffer/providers/google_cloud.rbs +8 -0
- data/sig/manual/riffer/wire.rbs +5 -0
- metadata +61 -5
- data/sig/_private/anthropic.rbs +0 -17
- data/sig/_private/riffer/providers/anthropic.rbs +0 -6
- data/sig/_private/riffer/providers/gemini.rbs +0 -7
|
@@ -169,6 +169,41 @@ class MyAgent < Riffer::Agent
|
|
|
169
169
|
end
|
|
170
170
|
```
|
|
171
171
|
|
|
172
|
+
## Anthropic-Compatible Endpoints
|
|
173
|
+
|
|
174
|
+
For a service that speaks the Anthropic Messages API, subclass `Riffer::Providers::AnthropicCompatible::MessagesAPI` instead of `Base`. It brings the request building, response parsing and streaming of the Anthropic provider; you supply the client. An endpoint that takes a bearer key can use `Riffer::Providers::Anthropic::Client` with its own `base_url`. For other auth, subclass `Riffer::HTTP::Client`:
|
|
175
|
+
|
|
176
|
+
```ruby
|
|
177
|
+
class AcmeClaude < Riffer::Providers::AnthropicCompatible::MessagesAPI
|
|
178
|
+
class Client < Riffer::HTTP::Client
|
|
179
|
+
def initialize(api_key:, connection: nil)
|
|
180
|
+
super(connection: connection)
|
|
181
|
+
@api_key = api_key
|
|
182
|
+
end
|
|
183
|
+
|
|
184
|
+
private
|
|
185
|
+
|
|
186
|
+
def url_for(path) = "https://llm.acme.example/#{path}"
|
|
187
|
+
def headers = { "api-key" => @api_key }
|
|
188
|
+
def error_label = "Acme"
|
|
189
|
+
end
|
|
190
|
+
|
|
191
|
+
private
|
|
192
|
+
|
|
193
|
+
def build_client
|
|
194
|
+
Client.new(api_key: ENV.fetch("ACME_API_KEY"))
|
|
195
|
+
end
|
|
196
|
+
|
|
197
|
+
# Only when the endpoint differs from POST v1/messages with the standard body:
|
|
198
|
+
def messages_path(model, stream:) = "models/#{model}:#{stream ? 'streamRawPredict' : 'rawPredict'}"
|
|
199
|
+
def request_body(params, stream:) = { anthropic_version: "acme-2025-01-01", **super.except(:model) }
|
|
200
|
+
end
|
|
201
|
+
|
|
202
|
+
Riffer::Providers::Repository.register(:acme) { AcmeClaude }
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
`messages_path` returns the path relative to the client's base URL; `request_body` returns the JSON body actually sent, and by default adds `stream: true` when streaming. Read credentials from your own configuration or environment in `build_client`, never from `ANTHROPIC_API_KEY`, so an Anthropic key is never sent to another vendor.
|
|
206
|
+
|
|
172
207
|
## Tool Support
|
|
173
208
|
|
|
174
209
|
Tools are converted in `build_request_params` and passed through to both `execute_generate` and `execute_stream`:
|
data/docs/providers/GEMINI.md
CHANGED
|
@@ -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
|
|
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
|
|
29
|
-
|
|
|
30
|
-
| `api_key`
|
|
31
|
-
| `base_url`
|
|
32
|
-
| `
|
|
33
|
-
|
|
34
|
-
|
|
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.
|
|
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::
|
|
45
|
-
| `post_stream(path, body) { \|chunk\| }` | POST `body` as JSON to `path`; yield raw response body chunks; raise `Riffer::
|
|
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-
|
|
53
|
-
model 'gemini/gemini-
|
|
54
|
-
model 'gemini/gemini-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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` key 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-
|
|
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` key 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
|