riffer 0.55.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.
- checksums.yaml +4 -4
- data/.release-please-manifest.json +1 -1
- data/CHANGELOG.md +18 -0
- data/README.md +2 -1
- data/UPGRADING.md +3 -0
- data/docs/AGENT_LIFECYCLE.md +1 -1
- data/docs/CONFIGURATION.md +48 -1
- data/docs/GUARDRAILS.md +2 -0
- data/docs/MESSAGES.md +112 -15
- data/docs/STABILITY.md +32 -0
- data/docs/STREAM_EVENTS.md +16 -0
- data/docs/TESTING.md +22 -1
- data/docs/providers/AMAZON_BEDROCK.md +1 -1
- data/docs/providers/ANTHROPIC.md +18 -14
- data/docs/providers/CUSTOM_PROVIDERS.md +24 -0
- data/docs/providers/GEMINI.md +1 -1
- data/docs/providers/GOOGLE_CLOUD.md +1 -1
- data/docs/providers/MOCK_PROVIDER.md +2 -0
- data/docs/providers/OPENAI.md +3 -1
- data/docs-site/manifest.yml +3 -0
- data/lib/riffer/agent/run.rb +28 -13
- data/lib/riffer/agent/session.rb +33 -10
- data/lib/riffer/config/future.rb +53 -0
- data/lib/riffer/config/pricing.rb +5 -15
- data/lib/riffer/config.rb +16 -0
- data/lib/riffer/deprecation/event.rb +25 -0
- data/lib/riffer/deprecation.rb +60 -0
- data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
- data/lib/riffer/messages/assistant/text_part.rb +52 -0
- data/lib/riffer/messages/assistant.rb +64 -17
- data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +25 -1
- data/lib/riffer/providers/anthropic_compatible/messages_api.rb +51 -29
- data/lib/riffer/providers/base.rb +15 -6
- data/lib/riffer/providers/open_ai.rb +21 -16
- data/lib/riffer/stream_events/server_tool_done.rb +21 -0
- data/lib/riffer/testing.rb +6 -0
- data/lib/riffer/version.rb +1 -1
- data/lib/riffer.rb +2 -0
- data/sig/generated/riffer/agent/run.rbs +5 -0
- data/sig/generated/riffer/agent/session.rbs +6 -0
- data/sig/generated/riffer/config/future.rbs +29 -0
- data/sig/generated/riffer/config/pricing.rbs +0 -9
- data/sig/generated/riffer/config.rbs +8 -0
- data/sig/generated/riffer/deprecation/event.rbs +17 -0
- data/sig/generated/riffer/deprecation.rbs +27 -0
- data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
- data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
- data/sig/generated/riffer/messages/assistant.rbs +24 -11
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +10 -0
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +18 -9
- data/sig/generated/riffer/providers/base.rbs +5 -0
- data/sig/generated/riffer/providers/open_ai.rbs +7 -2
- data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
- data/sig/generated/riffer/testing.rbs +4 -0
- data/sig/generated/riffer.rbs +3 -0
- data/sig/manual/riffer/deprecation.rbs +5 -0
- metadata +16 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 4eb9fc9eb011b6c16fe2e87bb6dcfc3a8a5ba3f0ae3b29b72f530e61fe1d300d
|
|
4
|
+
data.tar.gz: 9016cfeb1bde20ce4788673b1d6398c1f087ec47893c575cf8fc4998fd797b31
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: c9603251a779743eb3b8a8ad5d2b289924bd1e678595ec714b89602f5bea1c515516f9f7a2521ce0f67511bd602db0a2cb83d47c45b9cf364aead3aa0039c1b0
|
|
7
|
+
data.tar.gz: c243d5ca21b60801779c002bca9badc513ce6179066aa223f1351763f1aaded7d02fd37ac2695649aeab76ac7ed4a0d448e7f95feaf3a8b8aae722cd622f11d7
|
data/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.56.0](https://github.com/janeapp/riffer/compare/riffer/v0.55.0...riffer/v0.56.0) (2026-11-09)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### ⚠ BREAKING CHANGES
|
|
12
|
+
|
|
13
|
+
* **messages:** `Assistant#to_h` writes `parts` instead of `content`, `tool_calls` and `reasoning`, and `to_h` no longer accepts `parts:`. Build the old fields from `#content`, `#tool_calls` and `#reasoning` on the message. This also changes the assistant entries in `Riffer::Providers::Mock#calls` and `Riffer::Evals::ScenarioResult#to_h`.
|
|
14
|
+
|
|
15
|
+
### Features
|
|
16
|
+
|
|
17
|
+
* add Riffer::Deprecation for deprecation warnings ([#549](https://github.com/janeapp/riffer/issues/549)) ([6ad6046](https://github.com/janeapp/riffer/commit/6ad604647de1074d4f3f0739727940bcf06667fd))
|
|
18
|
+
* add Riffer.config.future for opt-in future flags ([#556](https://github.com/janeapp/riffer/issues/556)) ([6e49471](https://github.com/janeapp/riffer/commit/6e4947197d01672466606cd10541e39a2dcd521a))
|
|
19
|
+
* **messages:** keep assistant turns in order with Assistant#parts ([#527](https://github.com/janeapp/riffer/issues/527)) ([15e8eb9](https://github.com/janeapp/riffer/commit/15e8eb935f588a3937df449449d38712b0d12414))
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
### Bug Fixes
|
|
23
|
+
|
|
24
|
+
* **openai:** return web search sources and drop tool calls cut off by the token limit ([#541](https://github.com/janeapp/riffer/issues/541)) ([659e136](https://github.com/janeapp/riffer/commit/659e13672031f1867a5fd5345468db20487d3f27))
|
|
25
|
+
|
|
8
26
|
## [0.55.0](https://github.com/janeapp/riffer/compare/riffer/v0.54.0...riffer/v0.55.0) (2026-10-29)
|
|
9
27
|
|
|
10
28
|
|
data/README.md
CHANGED
|
@@ -63,6 +63,7 @@ Comprehensive guides live at [riffer.ai](https://riffer.ai):
|
|
|
63
63
|
- [MCP](https://riffer.ai/guides/mcp/) - Integrating third-party MCP servers
|
|
64
64
|
- [Serialization](https://riffer.ai/guides/serialization/) - Persisting and transferring agent definitions
|
|
65
65
|
- [Tracing](https://riffer.ai/guides/tracing/) - OpenTelemetry span contract and host wiring
|
|
66
|
+
- [Stability](https://riffer.ai/guides/stability/) - What's safe to depend on and how upgrades work
|
|
66
67
|
- [Providers](https://riffer.ai/guides/providers/overview/) - LLM provider adapters
|
|
67
68
|
|
|
68
69
|
The guide sources are in the [docs](docs/) directory.
|
|
@@ -159,7 +160,7 @@ Please follow the [Code of Conduct](https://github.com/janeapp/riffer/blob/main/
|
|
|
159
160
|
|
|
160
161
|
## Changelog
|
|
161
162
|
|
|
162
|
-
All notable changes to this project are documented in `CHANGELOG.md`.
|
|
163
|
+
All notable changes to this project are documented in `CHANGELOG.md`. Breaking releases come with an upgrade guide in [UPGRADING.md](UPGRADING.md).
|
|
163
164
|
|
|
164
165
|
## License
|
|
165
166
|
|
data/UPGRADING.md
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
# Upgrading
|
|
2
|
+
|
|
3
|
+
Upgrade guides for breaking releases will appear here. See the [stability policy](https://riffer.ai/guides/stability/) for when breaking changes can happen. To try a breaking release's new behaviour early, turn on its [future flag](https://riffer.ai/guides/configuration/#future-flags).
|
data/docs/AGENT_LIFECYCLE.md
CHANGED
|
@@ -270,7 +270,7 @@ If you need finer control over placeholder content (per-call shape, structured m
|
|
|
270
270
|
|
|
271
271
|
The session exposes a small set of in-place mutators that enforce the `tool_use` ↔ `tool_result` invariant on every operation. Use these to align history with external state (persisted transcript, partial output that wasn't actually delivered, etc.) without rebuilding the agent.
|
|
272
272
|
|
|
273
|
-
- **`agent.session.update(id:, **attrs)`** — In-place partial update. Looks up by message `id:`; builds a replacement of the same type with `attrs` overlaid on the existing fields. Use this to edit assistant content (`update(id:, content:)`), restate a system message, etc. When the target is an assistant and the update drops entries from `tool_calls`, matching `Tool` children are removed atomically.
|
|
273
|
+
- **`agent.session.update(id:, **attrs)`** — In-place partial update. Looks up by message `id:`; builds a replacement of the same type with `attrs` overlaid on the existing fields. Use this to edit assistant content (`update(id:, content:)`), restate a system message, etc. When the target is an assistant and the update drops entries from `tool_calls`, matching `Tool` children are removed atomically. An assistant update with `content:`, `tool_calls:` or `reasoning:` rebuilds the turn's [parts](MESSAGES.md#parts) in the default order, which drops server tool parts; pass `parts:` to replace them as given.
|
|
274
274
|
- **`agent.session.update(tool_call_id:, **attrs)`** — Same as above but looks up the tool result by `tool_call_id:`. Preserves `name` and `id`. Use this to upgrade a `discard_pending_tool_calls` placeholder once the real result is available (`update(tool_call_id:, content:, error: nil, error_type: nil)`).
|
|
275
275
|
- **`agent.session.remove(id:)`** — Removes a message; cascades to its `Tool` children when the target carries `tool_calls`. Raises if called on a `Tool` message (use `update(tool_call_id:, ...)` to rewrite a tool result instead).
|
|
276
276
|
- **`agent.session.discard_pending_tool_calls`** — Answers every unanswered `tool_use` with an `:interrupted` placeholder result and returns the filled `call_id`s (see "Discarding pending tool calls after an interrupt" above).
|
data/docs/CONFIGURATION.md
CHANGED
|
@@ -276,7 +276,7 @@ See [Model Catalog](CATALOG.md) for the file format, lookup, layering, and valid
|
|
|
276
276
|
|
|
277
277
|
### Pricing (deprecated)
|
|
278
278
|
|
|
279
|
-
`config.pricing` is deprecated and will be removed in a future release. Move rates into a [catalog file](CATALOG.md#pricing);
|
|
279
|
+
`config.pricing` is deprecated and will be removed in a future release. Move rates into a [catalog file](CATALOG.md#pricing); each line that calls `set` reports a [deprecation](#deprecations). Riffer still reads these rates as a fallback, and catalog pricing wins when both price a model.
|
|
280
280
|
|
|
281
281
|
```ruby
|
|
282
282
|
# before
|
|
@@ -291,6 +291,53 @@ end
|
|
|
291
291
|
|
|
292
292
|
`set` takes a `provider/model` id or an array of ids, plus `input:`, `output:`, and optional `cache_read:` and `cache_write:` rates per million tokens. The rates and cost formula are the same as [catalog pricing](CATALOG.md#pricing).
|
|
293
293
|
|
|
294
|
+
### Deprecations
|
|
295
|
+
|
|
296
|
+
A deprecated riffer call reports itself at least one release before it is removed. The report names the line in your code that made the call:
|
|
297
|
+
|
|
298
|
+
```
|
|
299
|
+
riffer: config.pricing is deprecated; move rates into a catalog file listed in config.catalog_files (see docs/CATALOG.md). Called from config/initializers/riffer.rb:4.
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
`config.deprecations` decides what happens:
|
|
303
|
+
|
|
304
|
+
```ruby
|
|
305
|
+
Riffer.configure do |config|
|
|
306
|
+
config.deprecations = ->(event) { Rails.logger.warn(event.to_s) }
|
|
307
|
+
end
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
| Value | Description |
|
|
311
|
+
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
312
|
+
| `:warn` (default) | Prints the report to stderr with `Kernel.warn`, once per deprecation per calling line. |
|
|
313
|
+
| `:raise` | Raises `Riffer::DeprecationError` on every call, so a test suite fails on each test that makes one. See [Testing — Deprecations](TESTING.md#deprecations). |
|
|
314
|
+
| `:silence` | Reports nothing. |
|
|
315
|
+
| A callable | Called with a `Riffer::Deprecation::Event` once per deprecation per calling line. The event has `id`, `message` and `location` (`"path:line"`); `to_s` is the report. |
|
|
316
|
+
|
|
317
|
+
Any other value raises `Riffer::ArgumentError`.
|
|
318
|
+
|
|
319
|
+
### Future flags
|
|
320
|
+
|
|
321
|
+
`config.future` lets you turn on new behaviour before it becomes the default, so you can try it and adapt ahead of the breaking release that switches it on for everyone:
|
|
322
|
+
|
|
323
|
+
```ruby
|
|
324
|
+
Riffer.configure do |config|
|
|
325
|
+
config.future.some_flag = true
|
|
326
|
+
end
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
A flag accepts booleans, `'true'`/`'false'`/`'1'`/`'0'`, `1`/`0`, or `nil` (which turns an opt-in flag off); any other value raises `Riffer::ArgumentError`. Setting a flag Riffer doesn't know raises `NoMethodError`.
|
|
330
|
+
|
|
331
|
+
A flag goes through three stages:
|
|
332
|
+
|
|
333
|
+
1. **Opt-in.** The flag is off by default, and setting it to `true` turns the new behaviour on.
|
|
334
|
+
2. **Default.** A [breaking release](STABILITY.md#breaking-releases) makes the new behaviour the default. The flag always reads as on, and setting it reports a [deprecation](#deprecations) saying it's no longer needed and can be removed.
|
|
335
|
+
3. **Removed.** A release later the flag is gone, and setting it raises `NoMethodError`.
|
|
336
|
+
|
|
337
|
+
| Flag | Stage | Description |
|
|
338
|
+
| -------- | ----- | ------------------------------- |
|
|
339
|
+
| _(none)_ | | Riffer has no future flags yet. |
|
|
340
|
+
|
|
294
341
|
### Message ID Strategy
|
|
295
342
|
|
|
296
343
|
Opt in to stable identifiers on every message for logging, persistence, or replay:
|
data/docs/GUARDRAILS.md
CHANGED
|
@@ -333,6 +333,8 @@ class TokenLimiter < Riffer::Guardrail
|
|
|
333
333
|
end
|
|
334
334
|
```
|
|
335
335
|
|
|
336
|
+
`Assistant.new(text)` builds a new turn with only that text, so this example also drops the response's tool calls and server tool parts. When a guardrail changes the text of a response that carries reasoning, server tool parts or tool calls, rebuild its `parts` instead; see [Messages — Editing a turn](MESSAGES.md#parts).
|
|
337
|
+
|
|
336
338
|
### Content Policy Filter
|
|
337
339
|
|
|
338
340
|
```ruby
|
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:
|
|
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,
|
|
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.
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
364
|
-
| ------------ | -------------------- |
|
|
365
|
-
| `System` | Joined with `"\n\n"` | —
|
|
366
|
-
| `User` | Joined with `"\n\n"` | `files` arrays concatenated
|
|
367
|
-
| `Assistant` | Joined with `"\n\n"` | `tool_calls` arrays concatenated | Yes |
|
|
368
|
-
| `Tool` | — | —
|
|
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.
|
data/docs/STREAM_EVENTS.md
CHANGED
|
@@ -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:
|
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 `
|
|
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`:
|
|
@@ -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
|
|
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
|
|
data/docs/providers/ANTHROPIC.md
CHANGED
|
@@ -29,12 +29,12 @@ Riffer.configure do |config|
|
|
|
29
29
|
end
|
|
30
30
|
```
|
|
31
31
|
|
|
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]
|
|
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
38
|
|
|
39
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
40
|
|
|
@@ -189,9 +189,11 @@ The reasoning is kept on the assistant message as [reasoning parts](../MESSAGES.
|
|
|
189
189
|
|
|
190
190
|
### Reasoning Replay
|
|
191
191
|
|
|
192
|
-
Riffer sends
|
|
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.
|
|
193
193
|
|
|
194
|
-
If you persist sessions,
|
|
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).
|
|
195
197
|
|
|
196
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.
|
|
197
199
|
|
|
@@ -222,16 +224,18 @@ end
|
|
|
222
224
|
|
|
223
225
|
Anthropic emits sources with `title` and `url` on the `WebSearchDone` event.
|
|
224
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
|
+
|
|
225
229
|
## Message Format
|
|
226
230
|
|
|
227
231
|
The provider converts Riffer messages to Anthropic format:
|
|
228
232
|
|
|
229
|
-
| Riffer Message | Anthropic Format
|
|
230
|
-
| -------------- |
|
|
231
|
-
| `System` | Added to `system` array as `{type: "text", text: ...}`
|
|
232
|
-
| `User` | `{role: "user", content: "..."}`
|
|
233
|
-
| `Assistant` | `{role: "assistant", content: [...]}
|
|
234
|
-
| `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", ...}]}` |
|
|
235
239
|
|
|
236
240
|
## Direct Provider Usage
|
|
237
241
|
|
|
@@ -259,6 +259,9 @@ Riffer::StreamEvents::ToolCallDone.new(
|
|
|
259
259
|
Riffer::StreamEvents::ReasoningDelta.new("thinking...")
|
|
260
260
|
Riffer::StreamEvents::ReasoningDone.new(part)
|
|
261
261
|
|
|
262
|
+
# Server tool blocks (if supported); see the Ordered Parts section
|
|
263
|
+
Riffer::StreamEvents::ServerToolDone.new(server_tool_part)
|
|
264
|
+
|
|
262
265
|
# Web search (if supported)
|
|
263
266
|
Riffer::StreamEvents::WebSearchStatus.new("searching", query: "search query")
|
|
264
267
|
Riffer::StreamEvents::WebSearchDone.new(
|
|
@@ -343,6 +346,27 @@ yielder << Riffer::StreamEvents::ReasoningDone.new(part)
|
|
|
343
346
|
|
|
344
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.
|
|
345
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
|
+
|
|
346
370
|
## Reasoning Level
|
|
347
371
|
|
|
348
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:
|
data/docs/providers/GEMINI.md
CHANGED
|
@@ -176,7 +176,7 @@ Gemini 3 models attach an opaque `thoughtSignature` to the first function call o
|
|
|
176
176
|
|
|
177
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
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
|
|
179
|
+
A function call that Gemini didn't sign, such as one another provider made before the conversation switched to Gemini, goes out with Gemini's placeholder signature (`skip_thought_signature_validator`), which Gemini accepts in place of a real one. That covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the reasoning when you store messages.
|
|
180
180
|
|
|
181
181
|
### Web Search
|
|
182
182
|
|
|
@@ -266,7 +266,7 @@ Gemini 3 models attach an opaque `thoughtSignature` to the first function call o
|
|
|
266
266
|
|
|
267
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
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
|
|
269
|
+
A function call without an Agent Platform signature goes out with Google's placeholder signature (`skip_thought_signature_validator`), which Agent Platform accepts in place of a real one. That happens when the call came from another provider, or from the Gemini Developer API, whose signatures Agent Platform rejects. It covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the reasoning when you store messages.
|
|
270
270
|
|
|
271
271
|
### Web Search
|
|
272
272
|
|
|
@@ -96,6 +96,8 @@ provider.calls
|
|
|
96
96
|
expect(provider.calls.last[:messages].last[:content]).to eq("Hi")
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
+
Each message is recorded as its `to_h`, so an assistant message has `parts` rather than `content` (see [Messages — Parts](../MESSAGES.md#parts)).
|
|
100
|
+
|
|
99
101
|
## Clearing State
|
|
100
102
|
|
|
101
103
|
Reset stubbed responses:
|
data/docs/providers/OPENAI.md
CHANGED
|
@@ -96,7 +96,7 @@ Each `reasoning` item in a Responses API output becomes [reasoning parts](../MES
|
|
|
96
96
|
|
|
97
97
|
The `:encrypted` part is always present, even when the response carried no `encrypted_content`, so the item's `id` is kept. When streaming, the parts are yielded as `ReasoningDone` events once the item completes; summary text still arrives as `ReasoningDelta` events before that.
|
|
98
98
|
|
|
99
|
-
On the next request, parts sharing an `id` go back as one `reasoning` item, ahead of the assistant's text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don't have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the
|
|
99
|
+
On the next request, parts sharing an `id` go back as one `reasoning` item, ahead of the assistant's text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don't have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the reasoning when you store them.
|
|
100
100
|
|
|
101
101
|
With `store` left on (the API default), OpenAI can resolve a replayed item from its `id` alone. With `model_options store: false`, the item can only be replayed from its encrypted payload, so request it explicitly:
|
|
102
102
|
|
|
@@ -118,6 +118,8 @@ model_options web_search: true
|
|
|
118
118
|
model_options web_search: {search_context_size: "medium"}
|
|
119
119
|
```
|
|
120
120
|
|
|
121
|
+
With web search on, riffer also adds `"web_search_call.action.sources"` to the request's `include`, keeping any entries you pass, so `WebSearchDone` carries the sources OpenAI searched.
|
|
122
|
+
|
|
121
123
|
## Example
|
|
122
124
|
|
|
123
125
|
```ruby
|
data/docs-site/manifest.yml
CHANGED