riffer 0.53.0 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/rules/rbs-inline.md +8 -8
  3. data/.release-please-manifest.json +1 -1
  4. data/.ruby-version +1 -1
  5. data/CHANGELOG.md +43 -0
  6. data/README.md +24 -0
  7. data/Steepfile +19 -0
  8. data/docs/AGENTS.md +101 -14
  9. data/docs/CATALOG.md +8 -8
  10. data/docs/CONFIGURATION.md +47 -16
  11. data/docs/MCP.md +3 -4
  12. data/docs/OVERVIEW.md +1 -1
  13. data/docs/STREAM_EVENTS.md +1 -1
  14. data/docs/TOOLS.md +15 -12
  15. data/docs/TRACING.md +1 -1
  16. data/docs/providers/AMAZON_BEDROCK.md +2 -0
  17. data/docs/providers/ANTHROPIC.md +32 -36
  18. data/docs/providers/CUSTOM_PROVIDERS.md +35 -0
  19. data/docs/providers/GEMINI.md +76 -25
  20. data/docs/providers/GOOGLE_CLOUD.md +363 -0
  21. data/docs/providers/PROVIDERS.md +30 -18
  22. data/docs-site/manifest.yml +3 -0
  23. data/lib/riffer/agent/structured_output.rb +28 -3
  24. data/lib/riffer/config/anthropic.rb +9 -0
  25. data/lib/riffer/config/gemini.rb +9 -0
  26. data/lib/riffer/config/google_cloud.rb +38 -0
  27. data/lib/riffer/config.rb +3 -0
  28. data/lib/riffer/http/client.rb +141 -0
  29. data/lib/riffer/http.rb +5 -0
  30. data/lib/riffer/mcp/client.rb +0 -1
  31. data/lib/riffer/params/any_of.rb +50 -0
  32. data/lib/riffer/params/format.rb +73 -0
  33. data/lib/riffer/params/param.rb +143 -19
  34. data/lib/riffer/params.rb +156 -30
  35. data/lib/riffer/providers/amazon_bedrock.rb +38 -5
  36. data/lib/riffer/providers/anthropic/client.rb +49 -0
  37. data/lib/riffer/providers/anthropic.rb +19 -452
  38. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +195 -0
  39. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +293 -0
  40. data/lib/riffer/providers/anthropic_compatible.rb +5 -0
  41. data/lib/riffer/providers/anthropic_vertex.rb +66 -0
  42. data/lib/riffer/providers/base.rb +13 -16
  43. data/lib/riffer/providers/gemini/client.rb +17 -85
  44. data/lib/riffer/providers/gemini.rb +213 -80
  45. data/lib/riffer/providers/google_cloud/client.rb +106 -0
  46. data/lib/riffer/providers/google_cloud.rb +99 -0
  47. data/lib/riffer/providers/repository.rb +2 -0
  48. data/lib/riffer/version.rb +1 -1
  49. data/lib/riffer/wire/sse.rb +51 -0
  50. data/lib/riffer/wire.rb +31 -0
  51. data/lib/riffer.rb +18 -0
  52. data/rbs_collection.lock.yaml +32 -4
  53. data/rbs_collection.yaml +2 -0
  54. data/sig/_private/faraday.rbs +8 -0
  55. data/sig/_private/googleauth.rbs +7 -0
  56. data/sig/generated/riffer/agent/structured_output.rbs +6 -0
  57. data/sig/generated/riffer/config/anthropic.rbs +6 -0
  58. data/sig/generated/riffer/config/gemini.rbs +6 -0
  59. data/sig/generated/riffer/config/google_cloud.rbs +28 -0
  60. data/sig/generated/riffer/config.rbs +2 -0
  61. data/sig/generated/riffer/http/client.rbs +59 -0
  62. data/sig/generated/riffer/http.rbs +4 -0
  63. data/sig/generated/riffer/params/any_of.rbs +21 -0
  64. data/sig/generated/riffer/params/format.rbs +39 -0
  65. data/sig/generated/riffer/params/param.rbs +27 -4
  66. data/sig/generated/riffer/params.rbs +38 -8
  67. data/sig/generated/riffer/providers/amazon_bedrock.rbs +14 -2
  68. data/sig/generated/riffer/providers/anthropic/client.rbs +34 -0
  69. data/sig/generated/riffer/providers/anthropic.rbs +5 -124
  70. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +71 -0
  71. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +99 -0
  72. data/sig/generated/riffer/providers/anthropic_compatible.rbs +4 -0
  73. data/sig/generated/riffer/providers/anthropic_vertex.rbs +45 -0
  74. data/sig/generated/riffer/providers/gemini/client.rbs +11 -34
  75. data/sig/generated/riffer/providers/gemini.rbs +66 -4
  76. data/sig/generated/riffer/providers/google_cloud/client.rbs +71 -0
  77. data/sig/generated/riffer/providers/google_cloud.rbs +64 -0
  78. data/sig/generated/riffer/wire/sse.rbs +23 -0
  79. data/sig/generated/riffer/wire.rbs +17 -0
  80. data/sig/generated/riffer.rbs +12 -0
  81. data/sig/manifest.yaml +2 -1
  82. data/sig/manual/riffer/params/format.rbs +5 -0
  83. data/sig/manual/riffer/providers/anthropic_compatible/messages_api.rbs +8 -0
  84. data/sig/manual/riffer/providers/gemini.rbs +8 -0
  85. data/sig/manual/riffer/providers/google_cloud.rbs +8 -0
  86. data/sig/manual/riffer/wire.rbs +5 -0
  87. metadata +66 -5
  88. data/sig/_private/anthropic.rbs +0 -17
  89. data/sig/_private/riffer/providers/anthropic.rbs +0 -6
  90. data/sig/_private/riffer/providers/gemini.rbs +0 -7
@@ -2,14 +2,6 @@
2
2
 
3
3
  The Anthropic provider connects to Claude models via the Anthropic API.
4
4
 
5
- ## Installation
6
-
7
- Add the Anthropic gem to your Gemfile:
8
-
9
- ```ruby
10
- gem 'anthropic'
11
- ```
12
-
13
5
  ## Configuration
14
6
 
15
7
  Configure your Anthropic API key:
@@ -20,18 +12,46 @@ Riffer.configure do |config|
20
12
  end
21
13
  ```
22
14
 
23
- For anything beyond the API key — timeouts, retries, proxies — supply your own `Anthropic::Client`:
15
+ When `config.anthropic.api_key` is unset, the provider reads `ANTHROPIC_API_KEY`; with neither set it raises `Riffer::ArgumentError`. Set `config.anthropic.base_url` (or `ANTHROPIC_BASE_URL`) to send requests somewhere other than `https://api.anthropic.com`, such as a gateway or proxy.
16
+
17
+ Riffer reads no other `ANTHROPIC_*` variables. The anthropic gem also read `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_CUSTOM_HEADERS`; riffer does not. The key is already sent as `Authorization: Bearer`, and custom headers go in the client's `headers:` (see [HTTP Client](#http-client)).
18
+
19
+ ## HTTP Client
20
+
21
+ The provider needs no Anthropic gem. Riffer ships its own Messages API transport, `Riffer::Providers::Anthropic::Client`, built on `Riffer::HTTP::Client`. The provider builds one from the configured credentials by default. To change timeouts, add retries or go through a proxy, build your own and assign it to `config.anthropic.client`:
24
22
 
25
23
  ```ruby
26
24
  Riffer.configure do |config|
27
- config.anthropic.client = Anthropic::Client.new(
25
+ config.anthropic.client = Riffer::Providers::Anthropic::Client.new(
28
26
  api_key: ENV['ANTHROPIC_API_KEY'],
29
- timeout: 60
27
+ connection: Faraday.new(request: { open_timeout: 10, read_timeout: 120 })
30
28
  )
31
29
  end
32
30
  ```
33
31
 
34
- The setting accepts a client instance or a no-argument `Proc`, resolved on every LLM call — see [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
32
+ | Option | Default | Description |
33
+ | ------------ | -------------------------------------- | ------------------------------------------------------------------- |
34
+ | `api_key` | required | Sent as `Authorization: Bearer <api_key>` |
35
+ | `base_url` | `https://api.anthropic.com` | API origin; requests go to `<base_url>/v1/messages` |
36
+ | `headers` | `{}` | Sent on every request; replaces riffer's headers of the same name |
37
+ | `connection` | Faraday defaults, 10s open / 600s read | Your own `Faraday::Connection`; see [Connections][connections] |
38
+
39
+ Timeouts, retries, proxies, beta headers and errors are covered in [Configuration → Connections][connections]. An API error becomes a `Riffer::APIError` whose message carries the Anthropic error type, e.g. `Anthropic API error (401): authentication_error: Invalid bearer token`. No requests are retried unless your connection adds retries.
40
+
41
+ The `anthropic-version` header is pinned to `2026-10-21`. To send another version, pass it in `headers:`:
42
+
43
+ ```ruby
44
+ Riffer::Providers::Anthropic::Client.new(
45
+ api_key: ENV['ANTHROPIC_API_KEY'],
46
+ headers: {'anthropic-version' => '2023-06-01'}
47
+ )
48
+ ```
49
+
50
+ Version `2026-10-21` removed `temperature`, `top_p` and `top_k`; sending any of them returns a 400. Pin `2023-06-01` to keep using them. See Anthropic's [API versions](https://platform.claude.com/docs/en/api/versioning) for the other changes.
51
+
52
+ The setting accepts a client instance or a no-argument `Proc`, resolved on every LLM call — see [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients). An `Anthropic::Client` from the anthropic gem is not accepted and raises `Riffer::ArgumentError`.
53
+
54
+ [connections]: ../CONFIGURATION.md#connections
35
55
 
36
56
  ## Supported Models
37
57
 
@@ -45,14 +65,6 @@ model 'anthropic/claude-opus-4-5-20251101'
45
65
 
46
66
  ## Model Options
47
67
 
48
- ### temperature
49
-
50
- Controls randomness:
51
-
52
- ```ruby
53
- model_options temperature: 0.7
54
- ```
55
-
56
68
  ### max_tokens
57
69
 
58
70
  Maximum tokens in response:
@@ -61,22 +73,6 @@ Maximum tokens in response:
61
73
  model_options max_tokens: 4096
62
74
  ```
63
75
 
64
- ### top_p
65
-
66
- Nucleus sampling parameter:
67
-
68
- ```ruby
69
- model_options top_p: 0.95
70
- ```
71
-
72
- ### top_k
73
-
74
- Top-k sampling parameter:
75
-
76
- ```ruby
77
- model_options top_k: 250
78
- ```
79
-
80
76
  ### thinking
81
77
 
82
78
  Enable extended thinking (reasoning) for supported models. Pass the thinking configuration hash directly as Anthropic expects:
@@ -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`:
@@ -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` 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-2.5-flash-lite",
216
+ model: "gemini-3.5-flash-lite",
165
217
  files: [file]
166
218
  )
167
219
  ```
@@ -170,5 +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