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
data/docs/MESSAGES.md CHANGED
@@ -57,7 +57,7 @@ msg = Riffer::Messages::Assistant.new("", tool_calls: [
57
57
  {id: "call_123", call_id: "call_123", name: "weather_tool", arguments: '{"city":"Tokyo"}'}
58
58
  ])
59
59
  msg.tool_calls # => [{id: "call_123", ...}]
60
- msg.to_h # => {role: "assistant", content: "", tool_calls: [...]}
60
+ msg.to_h # => {role: :assistant, parts: [{part: :tool_call, ...}]}
61
61
 
62
62
  # Accessing token usage data (when available from provider)
63
63
  if msg.token_usage
@@ -134,7 +134,7 @@ The `to_h` representation includes `structured_output` only when present:
134
134
 
135
135
  ```ruby
136
136
  msg = Riffer::Messages::Assistant.new('{"sentiment":"positive"}', structured_output: {sentiment: "positive"})
137
- msg.to_h # => {role: :assistant, content: '{"sentiment":"positive"}', structured_output: {sentiment: "positive"}}
137
+ msg.to_h # => {role: :assistant, parts: [{part: :text, text: '{"sentiment":"positive"}'}], structured_output: {sentiment: "positive"}}
138
138
  ```
139
139
 
140
140
  #### Reasoning
@@ -170,13 +170,14 @@ A `type` outside the three values raises `Riffer::ArgumentError`. `format` is a
170
170
 
171
171
  `reasoning?` is true when the message carries any part. `reasoning_text` joins the `text` of the `:text` and `:summary` parts with blank lines, skipping `:encrypted` parts, and is `nil` when there is nothing to join. The run's final assistant message projects its parts onto `response.reasoning` (see [Agent Lifecycle — Response Attributes](AGENT_LIFECYCLE.md#response-attributes)).
172
172
 
173
- Parts round-trip through `to_h` / `from_hash` like every other message field, so an application that persists sessions can store and replay them. The `reasoning` key is absent from `to_h` when the message has no parts, and each part omits the fields it doesn't carry:
173
+ Parts round-trip through `to_h` / `from_hash` like every other message field, so an application that persists sessions can store and replay them. `to_h` writes each reasoning part as a [`parts`](#parts) entry tagged `part: :reasoning`, and each part omits the fields it doesn't carry:
174
174
 
175
175
  ```ruby
176
176
  msg.to_h
177
- # => {role: :assistant, content: "42", reasoning: [
178
- # {type: :summary, text: "The user wants the answer.", format: "mock-v1"},
179
- # {type: :encrypted, data: "b3BhcXVl", format: "mock-v1"}
177
+ # => {role: :assistant, parts: [
178
+ # {part: :reasoning, type: :summary, text: "The user wants the answer.", format: "mock-v1"},
179
+ # {part: :reasoning, type: :encrypted, data: "b3BhcXVl", format: "mock-v1"},
180
+ # {part: :text, text: "42"}
180
181
  # ]}
181
182
 
182
183
  Riffer::Messages::Base.from_hash(msg.to_h).reasoning # => [ReasoningPart, ReasoningPart]
@@ -184,14 +185,108 @@ Riffer::Messages::Base.from_hash(msg.to_h).reasoning # => [ReasoningPart, Reaso
184
185
 
185
186
  **The replay contract.** A provider adapter replays only the parts whose `format` it recognizes and silently skips the rest, so history that travelled through another provider is never rejected. A part with no `format` is never replayed; adapters that surface reasoning text but cannot yet send it back emit their parts that way, so the text is kept for display without risking a rejected request. Parts are never reordered, merged, or edited — riffer treats them as opaque, because the provider's signature covers their exact bytes.
186
187
 
187
- An application that would rather not store parts can leave the key out when it serializes:
188
+ An application that would rather not store reasoning can drop the reasoning entries of `parts` when it serializes:
188
189
 
189
190
  ```ruby
190
- msg.to_h.except(:reasoning)
191
+ hash = msg.to_h
192
+ hash[:parts] = hash[:parts].reject { |part| part[:part] == :reasoning }
191
193
  ```
192
194
 
193
195
  To drop parts from the in-memory session mid-run instead, `Session#update(id:, reasoning: [])` rewrites the message in place; it needs [message ids](#ids) enabled to address it.
194
196
 
197
+ #### Parts
198
+
199
+ `parts` is the assistant turn in the order the provider produced it. `content`, `tool_calls` and `reasoning` are views over it. Some providers interleave reasoning, server-side tools and text in one turn, and Anthropic needs the turn back in that order: Claude signs each thinking block over every block before it. Sending earlier turns back unchanged also keeps the model's own reasoning and search results, and keeps the prompt cache warm, since the history doesn't change between requests.
200
+
201
+ A part is one of:
202
+
203
+ | Class | Holds |
204
+ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
205
+ | `TextPart` | One stretch of answer text (`text`). `data` keeps the provider's block when it carries more than the text, such as Anthropic citations |
206
+ | `ReasoningPart` | A thinking block (see [Reasoning](#reasoning)) |
207
+ | `ToolCall` | A function call riffer runs (see [Tool Calls](#tool-calls)) |
208
+ | `ServerToolPart` | A call (`kind: :call`) or result (`kind: :result`) of a tool the provider ran itself, such as web search |
209
+
210
+ `TextPart` carries:
211
+
212
+ | Field | Type | Description |
213
+ | -------- | --------- | ------------------------------------------------------------------------------------------------------ |
214
+ | `text` | `String` | The answer text |
215
+ | `data` | `String?` | The provider's whole block as JSON, kept when it carries more than the text (e.g. Anthropic citations) |
216
+ | `format` | `String?` | The wire format of `data`, owned by the adapter that produced it |
217
+
218
+ `ServerToolPart` carries:
219
+
220
+ | Field | Type | Description |
221
+ | -------- | --------- | --------------------------------------------------------------------------------------------- |
222
+ | `name` | `String` | The tool's name (e.g. `"web_search"`) |
223
+ | `kind` | `Symbol` | `:call` or `:result` |
224
+ | `data` | `String` | The provider's block as JSON, unchanged |
225
+ | `id` | `String?` | The provider's identifier, shared by a call and its result |
226
+ | `format` | `String?` | The wire format, owned by the adapter that produced the part (e.g. `"anthropic-messages-v1"`) |
227
+
228
+ A `kind` outside `:call` and `:result` raises `Riffer::ArgumentError`.
229
+
230
+ ```ruby
231
+ msg = Riffer::Messages::Assistant.new(parts: [
232
+ Riffer::Messages::Assistant::TextPart.new("Let me check. "),
233
+ Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :call, id: "srvtoolu_1", data: "{...}", format: "anthropic-messages-v1"),
234
+ Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :result, id: "srvtoolu_1", data: "{...}", format: "anthropic-messages-v1"),
235
+ Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: "", signature: "CAQS...", format: "anthropic-messages-v1"),
236
+ Riffer::Messages::Assistant::TextPart.new("The latest stable Ruby version is 4.0.9.")
237
+ ])
238
+
239
+ msg.content # => "Let me check. The latest stable Ruby version is 4.0.9."
240
+ msg.reasoning # => [ReasoningPart]
241
+ msg.reasoning? # => true; server tool parts don't count as reasoning
242
+ ```
243
+
244
+ - `content` joins the text parts with no separator.
245
+ - `Assistant.new(content, tool_calls:, reasoning:)` builds the parts in a fixed order: reasoning, then `content` as one text part (none when empty), then tool calls.
246
+ - Passing `parts:` together with `content`, `tool_calls:` or `reasoning:` raises `Riffer::ArgumentError`.
247
+ - `ServerToolPart#data` holds the provider's block as JSON, unchanged. It follows the same replay contract as reasoning: only the adapter that recognizes its `format` sends it back, and other adapters skip it. The same goes for a `TextPart` that carries `data`; other adapters send its `text`.
248
+
249
+ `to_h` writes the turn as a `parts` key, so it keeps the order, the server tool parts and the `data` of text parts. Each entry is the part's own hash plus a `part` tag (`:text`, `:reasoning`, `:tool_call` or `:server_tool`). It doesn't write `content`, `tool_calls` or `reasoning`; read those from the message:
250
+
251
+ ```ruby
252
+ msg.to_h
253
+ # => {role: :assistant, parts: [
254
+ # {part: :text, text: "Let me check. "},
255
+ # {part: :server_tool, name: "web_search", kind: :call, data: "{...}", id: "srvtoolu_1", format: "anthropic-messages-v1"},
256
+ # ...
257
+ # ]}
258
+
259
+ {content: msg.content, tool_calls: msg.tool_calls.map(&:to_h), reasoning: msg.reasoning.map(&:to_h)}
260
+ ```
261
+
262
+ `from_hash` reads this shape and the older one with `content`, `tool_calls` and `reasoning` keys, so stored sessions still load. Rebuilt from the older shape, the turn is in the fixed order, without server tool parts or the `data` of text parts. A hash with `parts` and a non-nil `content`, or a non-empty `tool_calls` or `reasoning`, raises `Riffer::ArgumentError`.
263
+
264
+ **Editing a turn.** Riffer sends the parts back as they are. When you change a turn's text (in an output guardrail, or with `Session#update`), keeping the rest of the turn consistent is up to you:
265
+
266
+ - Drop that turn's reasoning parts. They were signed over the old text, so Anthropic would reject them or drop them silently, and they may still hold the text you removed.
267
+ - Keep server tool parts and tool calls, so the model doesn't search again and tool results keep their call.
268
+ - Put the new text after the last server tool part and before the first tool call.
269
+
270
+ ```ruby
271
+ def redact(message, text)
272
+ kept = message.parts.reject do |part|
273
+ part.is_a?(Riffer::Messages::Assistant::ReasoningPart) || part.is_a?(Riffer::Messages::Assistant::TextPart)
274
+ end
275
+ index = kept.index { |part| part.is_a?(Riffer::Messages::Assistant::ToolCall) } || kept.length
276
+ parts = kept.insert(index, Riffer::Messages::Assistant::TextPart.new(text))
277
+
278
+ Riffer::Messages::Assistant.new(
279
+ parts: parts,
280
+ id: message.id,
281
+ token_usage: message.token_usage,
282
+ finish_reason: message.finish_reason,
283
+ finish_reason_raw: message.finish_reason_raw
284
+ )
285
+ end
286
+ ```
287
+
288
+ `Assistant.new(text)` and `Session#update(id:, content:)` don't follow these rules. They rebuild the turn in the fixed order, which keeps the reasoning and drops server tool parts. Use `Session#update(id:, parts:)` to replace the parts as given.
289
+
195
290
  ### Tool
196
291
 
197
292
  Tool messages contain the results of tool executions:
@@ -360,12 +455,14 @@ Without this step, the same model can receive different input depending on the p
360
455
 
361
456
  ### Merge rules
362
457
 
363
- | Message type | Content | Auxiliary data | Merged? |
364
- | ------------ | -------------------- | -------------------------------- | ---------------------------------------- |
365
- | `System` | Joined with `"\n\n"` | — | Yes |
366
- | `User` | Joined with `"\n\n"` | `files` arrays concatenated | Yes |
367
- | `Assistant` | Joined with `"\n\n"` | `tool_calls` arrays concatenated | Yes |
368
- | `Tool` | — | — | Never (each has a unique `tool_call_id`) |
458
+ | Message type | Content | Auxiliary data | Merged? |
459
+ | ------------ | -------------------- | ------------------------------------------------ | ---------------------------------------- |
460
+ | `System` | Joined with `"\n\n"` | — | Yes |
461
+ | `User` | Joined with `"\n\n"` | `files` arrays concatenated | Yes |
462
+ | `Assistant` | Joined with `"\n\n"` | `tool_calls` and `reasoning` arrays concatenated | Yes |
463
+ | `Tool` | — | — | Never (each has a unique `tool_call_id`) |
464
+
465
+ When either assistant message has [parts](#parts) its fields can't rebuild, the merged message concatenates the two `parts` lists instead, with a `"\n\n"` text part between the texts.
369
466
 
370
467
  ### Example
371
468
 
@@ -434,7 +531,7 @@ class Riffer::Messages::Base
434
531
  end
435
532
  ```
436
533
 
437
- Subclasses implement `role` and optionally extend `to_h` with additional fields.
534
+ Subclasses implement `role` and optionally extend `to_h` with additional fields. `Assistant` writes `parts` in place of `content`.
438
535
 
439
536
  ## Editing history after the fact
440
537
 
data/docs/STABILITY.md ADDED
@@ -0,0 +1,32 @@
1
+ # Stability
2
+
3
+ This page covers which parts of Riffer you can depend on, how changes to them are announced, and how breaking releases work. Riffer is not at 1.0 yet; the [roadmap](https://github.com/janeapp/riffer/issues/528) tracks the path there.
4
+
5
+ ## Public API
6
+
7
+ The public API is everything documented in these guides. You can build on it, and it changes only in the ways this page describes.
8
+
9
+ Everything else is internal, even when Ruby lets you reach it. That includes classes, methods and constants that appear in the [API reference](https://riffer.ai/api/) but not in a guide. Internal code can change in any release without notice. At 1.0, every public constant will be documented and everything else marked private.
10
+
11
+ ## Experimental features
12
+
13
+ Experimental features are labelled _experimental_ in the guides, like the [prompted structured output strategy](AGENTS.md#structured-output-strategy-experimental). They can change in any minor release, and the [CHANGELOG](https://github.com/janeapp/riffer/blob/main/CHANGELOG.md) notes each change.
14
+
15
+ ## Deprecations
16
+
17
+ A breaking change to the public API lands first as a new API or an [opt-in flag](CONFIGURATION.md#future-flags), and the old way prints a deprecation warning. The warning appears for at least one release before the old way is removed, and it names the earliest version it can be removed in. For larger changes, it also names a date.
18
+
19
+ ## Breaking releases
20
+
21
+ Before 1.0, any minor release can include breaking changes, but never without notice: an earlier release deprecates what's changing first, so you'll see the warnings before anything breaks. Each breaking release comes with an upgrade guide in [UPGRADING.md](https://github.com/janeapp/riffer/blob/main/UPGRADING.md), and the CHANGELOG lists its changes under **⚠ BREAKING CHANGES**.
22
+
23
+ After 1.0, breaking changes ship only in major versions.
24
+
25
+ ## Saved formats
26
+
27
+ Saved formats are the data Riffer produces for you to store and load later, such as [serialized agents](SERIALIZATION.md) and [messages persisted with `to_h`](MESSAGES.md#parts).
28
+
29
+ - Riffer can read a new format at least one release before it starts writing it, so a deploy that runs a release alongside the one before it keeps working.
30
+ - Anything saved by a 1.x release loads in every later 1.x release.
31
+
32
+ See [Serialization → Versioning](SERIALIZATION.md#versioning) for how agent data records its format version.
@@ -55,6 +55,8 @@ event.to_h # => {role: :assistant, content: "Hello, how can I help you?"}
55
55
 
56
56
  Fires once per model response, after its last `TextDelta`, and contains the response's full text: every text block the provider returned, concatenated in order, so it always equals the joined `TextDelta` contents. A response that carries no text (for example, only tool calls) emits no `TextDone`.
57
57
 
58
+ The agent loop builds the message's [text parts](MESSAGES.md#parts) from the `TextDelta` events: the deltas between two other parts (reasoning, a tool call, a server tool block) form one text part. An adapter that sends no deltas gets one text part, from `TextDone`, at the end of the turn.
59
+
58
60
  ### ToolCallDelta
59
61
 
60
62
  Emitted when tool call arguments are being streamed:
@@ -156,6 +158,20 @@ event.to_h # => {role: :assistant, query: "Ruby language", sources: [...]}
156
158
 
157
159
  Contains the search query and an array of source hashes with `title` and `url` keys.
158
160
 
161
+ ### ServerToolDone
162
+
163
+ Emitted when a block from a tool the provider ran itself (such as web search) is complete. It carries the block for replay; use `WebSearchStatus` and `WebSearchDone` to show progress.
164
+
165
+ ```ruby
166
+ part = Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :call, data: "{...}", format: "anthropic-messages-v1")
167
+ event = Riffer::StreamEvents::ServerToolDone.new(part)
168
+ event.role # => :assistant
169
+ event.part # => the ServerToolPart
170
+ event.to_h # => {role: :assistant, part: {name: "web_search", kind: :call, data: "{...}", format: "anthropic-messages-v1"}}
171
+ ```
172
+
173
+ The agent loop adds `part` to the assistant message's [parts](MESSAGES.md#parts). Only Anthropic emits it today.
174
+
159
175
  ### GuardrailTripwire
160
176
 
161
177
  Emitted when a guardrail blocks execution during streaming:
@@ -310,7 +326,7 @@ When an agent uses tools during streaming, the flow is:
310
326
  5. More text events stream in
311
327
  6. Repeat until no more tool calls
312
328
 
313
- > **Note:** When `web_search` is enabled, `WebSearchStatus` and `WebSearchDone` events may appear before text events as the provider performs a server-side search.
329
+ > **Note:** When `web_search` is enabled, `WebSearchStatus` and `WebSearchDone` events may appear before text events as the provider performs a server-side search. Gemini sends its `WebSearchDone` after the text.
314
330
 
315
331
  ```ruby
316
332
  agent.stream("What's the weather in Tokyo?").each do |event|
data/docs/TESTING.md CHANGED
@@ -16,7 +16,7 @@ require 'riffer/testing/rspec'
16
16
  require 'riffer/testing/minitest'
17
17
  ```
18
18
 
19
- Either one adds `stub_agent` and `stub_tool` to every example and cleans up after each one. Neither RSpec nor minitest is a riffer dependency; the adapter files are only loaded when you require them yourself.
19
+ Either one adds `stub_agent`, `stub_tool` and `allow_deprecations` to every example and cleans up after each one. Neither RSpec nor minitest is a riffer dependency; the adapter files are only loaded when you require them yourself.
20
20
 
21
21
  ## Stubbing a tool
22
22
 
@@ -110,6 +110,27 @@ end
110
110
 
111
111
  Tracking lives on `Riffer::Testing` itself, so `Riffer::Testing.stub_tool(...)` outside an example and `stub_tool(...)` inside one share one list. Tracking is not synchronized — stub from a single-threaded test, before concurrent lookups begin.
112
112
 
113
+ ## Deprecations
114
+
115
+ Make your suite fail when it hits a deprecated riffer call, so you find each one before an upgrade removes it:
116
+
117
+ ```ruby
118
+ # test/test_helper.rb
119
+ Riffer.config.deprecations = :raise
120
+ ```
121
+
122
+ Every deprecated call then raises `Riffer::DeprecationError`, naming the line that made it. A test that uses a deprecated call on purpose wraps it in `allow_deprecations`:
123
+
124
+ ```ruby
125
+ it 'still reads legacy pricing' do
126
+ allow_deprecations { Riffer.config.pricing.set('openai/gpt-5', input: 1.0, output: 2.0) }
127
+
128
+ # ...
129
+ end
130
+ ```
131
+
132
+ `allow_deprecations` silences deprecations until the block returns or raises, and returns the block's value. It applies to the current thread or fiber and to threads and fibers started inside the block; other threads keep reporting. It is also available as `Riffer::Testing.allow_deprecations` outside an example. See [Configuration — Deprecations](CONFIGURATION.md#deprecations) for the other modes.
133
+
113
134
  ## When a stub leaks
114
135
 
115
136
  Stubbing an identifier that is already taken raises `Riffer::DuplicateIdentifierError`:
data/docs/TOOLS.md CHANGED
@@ -105,16 +105,16 @@ Options:
105
105
 
106
106
  ### Supported Types
107
107
 
108
- | Ruby Type | JSON Schema Type |
109
- | -------------------------- | ------------------ |
110
- | `String` | `string` |
111
- | `Integer` | `integer` |
112
- | `Float` | `number` |
113
- | `Riffer::Params::Boolean` | `boolean` |
114
- | `TrueClass` / `FalseClass` | `boolean` |
115
- | `Array` | `array` |
116
- | `Hash` | `object` |
117
- | `Riffer::Params::AnyOf` | `anyOf` of objects |
108
+ | Ruby Type | JSON Schema Type |
109
+ | -------------------------- | -------------------------------- |
110
+ | `String` | `string` |
111
+ | `Integer` | `integer` |
112
+ | `Float` | `number` |
113
+ | `Riffer::Params::Boolean` | `boolean` |
114
+ | `TrueClass` / `FalseClass` | `boolean` |
115
+ | `Array` | `array` |
116
+ | `Hash` | `object` |
117
+ | `Riffer::Params::AnyOf` | `anyOf` of objects or primitives |
118
118
 
119
119
  `Riffer::Params::Boolean` is the preferred way to declare boolean parameters. `TrueClass` and `FalseClass` continue to work for backwards compatibility.
120
120
 
@@ -122,7 +122,7 @@ A `Float` param accepts a whole number too, since JSON Schema's `number` covers
122
122
 
123
123
  ### Nested Parameters
124
124
 
125
- Tool params support the same nested DSL as structured output — nested objects (`Hash` with block), typed arrays (`Array, of:`), arrays of arrays (`Array, of: [Integer]`), arrays of objects (`Array` with block), and either/or shapes (`Riffer::Params::AnyOf` with `variant` blocks). See the [structured output section in Agents](AGENTS.md#nested-objects) for full syntax.
125
+ Tool params support the same nested DSL as structured output — nested objects (`Hash` with block), typed arrays (`Array, of:`), arrays of arrays (`Array, of: [Integer]`), arrays of objects (`Array` with block), and either/or shapes (`Riffer::Params::AnyOf` with `variant`s). See the [structured output section in Agents](AGENTS.md#nested-objects) for full syntax.
126
126
 
127
127
  ```ruby
128
128
  class CreateOrderTool < Riffer::Tool
data/docs/TRACING.md CHANGED
@@ -267,7 +267,7 @@ When enabled, content is serialized as GenAI-semconv JSON strings. File attachme
267
267
 
268
268
  ## Provider names
269
269
 
270
- `gen_ai.provider.name` carries a GenAI-semconv well-known value where one exists: `openai`, `anthropic`, `aws.bedrock`, `azure.ai.openai`, `gcp.gemini`, `openrouter`. A custom provider that doesn't override the value defaults to the snake_cased form of its class name, so enabling tracing never breaks an otherwise-working provider.
270
+ `gen_ai.provider.name` carries a GenAI-semconv well-known value where one exists: `openai`, `anthropic`, `aws.bedrock`, `azure.ai.openai`, `gcp.gemini`, `gcp.vertex_ai`, `openrouter`. A custom provider that doesn't override the value defaults to the snake_cased form of its class name, so enabling tracing never breaks an otherwise-working provider.
271
271
 
272
272
  ## Stability
273
273
 
@@ -195,7 +195,7 @@ The agent-level [`reasoning`](../AGENTS.md#reasoning) setting defaults to Claude
195
195
 
196
196
  Riffer sends the reasoning back to Bedrock on every later turn. How much of it Claude uses depends on the model; some only use the reasoning from the current tool-calling turn. For tool calls, sending it back is required: when thinking is enabled, Claude needs its earlier reasoning back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
197
197
 
198
- If you persist sessions, keep the `reasoning` key when you store messages (see [Messages — Reasoning](../MESSAGES.md#reasoning)). If you drop it, later turns lose the model's earlier reasoning, and a tool-calling turn with thinking enabled may be rejected.
198
+ If you persist sessions, keep the reasoning when you store messages (see [Messages — Reasoning](../MESSAGES.md#reasoning)). If you drop it, later turns lose the model's earlier reasoning, and a tool-calling turn with thinking enabled may be rejected.
199
199
 
200
200
  Only reasoning that Bedrock produced is sent back to Bedrock. A conversation that switches providers midway still works: reasoning from other providers is kept on the messages but left out of Bedrock requests.
201
201
 
@@ -212,6 +212,8 @@ response = provider.generate_text(
212
212
  )
213
213
  ```
214
214
 
215
+ Converse requires every document to have a name, unique across the request, made only of letters, digits, single spaces, hyphens, parentheses and square brackets, and at most 200 characters long. Riffer builds it from the file's `filename`: the extension is dropped, other characters become hyphens, the name is cut to 200 characters, a document without a filename is named `document`, and a repeated name gets a counter (`invoice`, `invoice (2)`). The model can see the name.
216
+
215
217
  Any other URL scheme (e.g. `https://`) isn't something Bedrock accepts as a reference, so riffer downloads the file itself and sends the raw bytes — see [File Downloads](../CONFIGURATION.md#file-downloads) for the `allow_downloads` policy this requires.
216
218
 
217
219
  **A `sha256:` on an `s3://` `FilePart` is a combination that always fails with the default setup.** Setting `sha256:` forces riffer to download and verify the file itself before Bedrock ever sees it, regardless of the URL scheme — but riffer's default downloader only fetches `https://` URLs, so an `s3://` source can never be verified out of the box. Either configure a custom `Riffer.config.files.downloader` that can reach S3, or omit `sha256:` and let the `s3://` URI pass straight through to Bedrock unverified.
@@ -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:
@@ -193,9 +189,11 @@ The reasoning is kept on the assistant message as [reasoning parts](../MESSAGES.
193
189
 
194
190
  ### Reasoning Replay
195
191
 
196
- Riffer sends the reasoning back to Anthropic on every later turn, as `thinking` and `redacted_thinking` blocks ahead of the message's text and `tool_use` blocks, in their original order and unchanged. For tool calls, sending it back is required: when thinking is enabled, Claude needs its earlier thinking blocks back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
192
+ Riffer sends every earlier turn back to Anthropic as the API returned it: the `thinking`, `redacted_thinking`, text, web search and `tool_use` blocks, in their original order and unchanged (see [Messages — Parts](../MESSAGES.md#parts)). Order matters because Claude signs each thinking block over everything before it, including earlier blocks of the same turn. A turn sent back in a different order loses that reasoning, or is rejected with a 400 on accounts that enforce the binding. For tool calls, sending the reasoning back is required: when thinking is enabled, Claude needs its earlier thinking blocks back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
197
193
 
198
- If you persist sessions, keep the `reasoning` key when you store messages (see [Messages — Reasoning](../MESSAGES.md#reasoning)). If you drop it, later turns lose the model's earlier reasoning, and a tool-calling turn with thinking enabled may be rejected.
194
+ If you persist sessions, `to_h` keeps the web search results and the turn's block order (see [Messages — Parts](../MESSAGES.md#parts)). Dropping the reasoning loses the model's earlier thinking, and a tool-calling turn with thinking enabled may be rejected.
195
+
196
+ If you change a turn's text, drop that turn's reasoning yourself; see [Editing a turn](../MESSAGES.md#parts).
199
197
 
200
198
  Only reasoning that this provider produced is sent back to Anthropic. A conversation that switches providers midway still works: reasoning from other providers (including OpenRouter's `anthropic-claude-v1` parts) is kept on the messages but left out of Anthropic requests.
201
199
 
@@ -226,16 +224,18 @@ end
226
224
 
227
225
  Anthropic emits sources with `title` and `url` on the `WebSearchDone` event.
228
226
 
227
+ Each `server_tool_use` block and its result block (`web_search_tool_result`, or `code_execution_tool_result` when a newer web search version runs the search from code execution) is kept on the assistant message as a `ServerToolPart` (see [Messages — Parts](../MESSAGES.md#parts)), and a streamed one also arrives as a `ServerToolDone` event. With `generate`, text blocks with citations keep their block too; a streamed turn keeps the text without its citations. Later turns send them back in place, so Claude reuses the results instead of searching again.
228
+
229
229
  ## Message Format
230
230
 
231
231
  The provider converts Riffer messages to Anthropic format:
232
232
 
233
- | Riffer Message | Anthropic Format |
234
- | -------------- | --------------------------------------------------------------- |
235
- | `System` | Added to `system` array as `{type: "text", text: ...}` |
236
- | `User` | `{role: "user", content: "..."}` |
237
- | `Assistant` | `{role: "assistant", content: [...]}` with text/tool_use blocks |
238
- | `Tool` | `{role: "user", content: [{type: "tool_result", ...}]}` |
233
+ | Riffer Message | Anthropic Format |
234
+ | -------------- | ------------------------------------------------------------------------ |
235
+ | `System` | Added to `system` array as `{type: "text", text: ...}` |
236
+ | `User` | `{role: "user", content: "..."}` |
237
+ | `Assistant` | `{role: "assistant", content: [...]}`, one block per part, in part order |
238
+ | `Tool` | `{role: "user", content: [{type: "tool_result", ...}]}` |
239
239
 
240
240
  ## Direct Provider Usage
241
241
 
@@ -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`:
@@ -224,6 +259,9 @@ Riffer::StreamEvents::ToolCallDone.new(
224
259
  Riffer::StreamEvents::ReasoningDelta.new("thinking...")
225
260
  Riffer::StreamEvents::ReasoningDone.new(part)
226
261
 
262
+ # Server tool blocks (if supported); see the Ordered Parts section
263
+ Riffer::StreamEvents::ServerToolDone.new(server_tool_part)
264
+
227
265
  # Web search (if supported)
228
266
  Riffer::StreamEvents::WebSearchStatus.new("searching", query: "search query")
229
267
  Riffer::StreamEvents::WebSearchDone.new(
@@ -308,6 +346,27 @@ yielder << Riffer::StreamEvents::ReasoningDone.new(part)
308
346
 
309
347
  If your adapter surfaces reasoning text but cannot yet replay it, call `yield_reasoning_done(yielder, text)` instead. It wraps the text in a `:text` part with no `format`, which persists for display and is skipped on replay.
310
348
 
349
+ ## Ordered Parts
350
+
351
+ By default the base class builds the assistant message's [parts](../MESSAGES.md#parts) from `extract_reasoning`, `extract_content` and `extract_tool_calls`, in that order. If your provider interleaves blocks in one turn and needs them back in that order, override `extract_parts` instead and return every block as a part, in response order:
352
+
353
+ ```ruby
354
+ def extract_parts(response)
355
+ response.blocks.filter_map do |block|
356
+ case block.type
357
+ when "text" then Riffer::Messages::Assistant::TextPart.new(block.text)
358
+ when "thinking" then Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: block.text, signature: block.signature, format: "my-provider-v1")
359
+ when "tool_call" then Riffer::Messages::Assistant::ToolCall.new(call_id: block.id, name: block.name, arguments: block.arguments)
360
+ when "search" then Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :call, id: block.id, data: block.to_json, format: "my-provider-v1")
361
+ end
362
+ end
363
+ end
364
+ ```
365
+
366
+ Then replay by walking `message.parts` rather than reading `content`, `tool_calls` and `reasoning` separately, and skip parts whose `format` you don't recognize.
367
+
368
+ For streaming, emit `ServerToolDone` for each server tool block, and keep text deltas, `ReasoningDone` and `ToolCallDone` in the order the blocks arrive. The agent loop builds the parts in that order.
369
+
311
370
  ## Reasoning Level
312
371
 
313
372
  When an agent sets [`reasoning`](../AGENTS.md#reasoning), riffer resolves the level to `model_options` params before calling `build_request_params`, so your provider receives ordinary options and never sees the level itself. It uses the model's [catalog](../CATALOG.md#reasoning) entry under your registration key first, then your provider's default. Override the private `default_reasoning_options` to supply one: