riffer 0.55.0 → 0.57.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 (114) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +37 -0
  4. data/README.md +3 -2
  5. data/UPGRADING.md +3 -0
  6. data/docs/AGENTS.md +105 -50
  7. data/docs/AGENT_LIFECYCLE.md +2 -2
  8. data/docs/CONFIGURATION.md +54 -3
  9. data/docs/EVALS.md +2 -0
  10. data/docs/GUARDRAILS.md +2 -0
  11. data/docs/MCP.md +36 -0
  12. data/docs/MESSAGES.md +125 -15
  13. data/docs/OVERVIEW.md +7 -7
  14. data/docs/SERIALIZATION.md +12 -2
  15. data/docs/SKILLS.md +1 -1
  16. data/docs/STABILITY.md +32 -0
  17. data/docs/STREAM_EVENTS.md +16 -0
  18. data/docs/TESTING.md +22 -1
  19. data/docs/TOOLS.md +93 -37
  20. data/docs/TOOL_ADVANCED.md +7 -0
  21. data/docs/providers/AMAZON_BEDROCK.md +7 -3
  22. data/docs/providers/ANTHROPIC.md +53 -16
  23. data/docs/providers/AZURE_OPENAI.md +9 -3
  24. data/docs/providers/CUSTOM_PROVIDERS.md +43 -0
  25. data/docs/providers/GEMINI.md +9 -5
  26. data/docs/providers/GOOGLE_CLOUD.md +10 -5
  27. data/docs/providers/MOCK_PROVIDER.md +4 -0
  28. data/docs/providers/OPENAI.md +28 -4
  29. data/docs/providers/OPENROUTER.md +11 -3
  30. data/docs/providers/PROVIDERS.md +1 -1
  31. data/docs-site/index.html.erb +1 -1
  32. data/docs-site/manifest.yml +3 -0
  33. data/lib/riffer/agent/config.rb +21 -0
  34. data/lib/riffer/agent/context.rb +36 -18
  35. data/lib/riffer/agent/run.rb +82 -21
  36. data/lib/riffer/agent/serializer.rb +5 -0
  37. data/lib/riffer/agent/session.rb +34 -10
  38. data/lib/riffer/agent.rb +43 -0
  39. data/lib/riffer/config/future.rb +53 -0
  40. data/lib/riffer/config/mcp.rb +17 -0
  41. data/lib/riffer/config/pricing.rb +5 -15
  42. data/lib/riffer/config.rb +28 -1
  43. data/lib/riffer/deprecation/event.rb +25 -0
  44. data/lib/riffer/deprecation.rb +60 -0
  45. data/lib/riffer/evals/evaluator.rb +8 -1
  46. data/lib/riffer/evals/evaluator_runner.rb +1 -0
  47. data/lib/riffer/evals/judge.rb +2 -2
  48. data/lib/riffer/evals.rb +2 -0
  49. data/lib/riffer/mcp/search_tool.rb +1 -1
  50. data/lib/riffer/mcp.rb +7 -0
  51. data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
  52. data/lib/riffer/messages/assistant/text_part.rb +52 -0
  53. data/lib/riffer/messages/assistant.rb +64 -17
  54. data/lib/riffer/messages/tool.rb +6 -2
  55. data/lib/riffer/params/any_of.rb +5 -8
  56. data/lib/riffer/params/boolean.rb +1 -1
  57. data/lib/riffer/params/param.rb +96 -67
  58. data/lib/riffer/params.rb +50 -71
  59. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +28 -11
  60. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +136 -38
  61. data/lib/riffer/providers/base.rb +57 -12
  62. data/lib/riffer/providers/deferred_tool_gateway/sink.rb +54 -0
  63. data/lib/riffer/providers/deferred_tool_gateway/tool.rb +17 -0
  64. data/lib/riffer/providers/deferred_tool_gateway.rb +150 -0
  65. data/lib/riffer/providers/gemini.rb +5 -5
  66. data/lib/riffer/providers/mock.rb +6 -0
  67. data/lib/riffer/providers/open_ai.rb +59 -26
  68. data/lib/riffer/skills/activate_tool.rb +1 -1
  69. data/lib/riffer/stream_events/server_tool_done.rb +21 -0
  70. data/lib/riffer/testing.rb +6 -0
  71. data/lib/riffer/tool.rb +92 -2
  72. data/lib/riffer/tools/response.rb +11 -2
  73. data/lib/riffer/version.rb +1 -1
  74. data/lib/riffer.rb +2 -0
  75. data/sig/generated/riffer/agent/config.rbs +13 -1
  76. data/sig/generated/riffer/agent/context.rbs +16 -0
  77. data/sig/generated/riffer/agent/run.rbs +19 -2
  78. data/sig/generated/riffer/agent/session.rbs +6 -0
  79. data/sig/generated/riffer/agent.rbs +13 -0
  80. data/sig/generated/riffer/config/future.rbs +29 -0
  81. data/sig/generated/riffer/config/mcp.rbs +7 -0
  82. data/sig/generated/riffer/config/pricing.rbs +0 -9
  83. data/sig/generated/riffer/config.rbs +13 -1
  84. data/sig/generated/riffer/deprecation/event.rbs +17 -0
  85. data/sig/generated/riffer/deprecation.rbs +27 -0
  86. data/sig/generated/riffer/evals/evaluator.rbs +4 -0
  87. data/sig/generated/riffer/evals.rbs +1 -0
  88. data/sig/generated/riffer/mcp.rbs +1 -0
  89. data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
  90. data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
  91. data/sig/generated/riffer/messages/assistant.rbs +24 -11
  92. data/sig/generated/riffer/messages/tool.rbs +4 -2
  93. data/sig/generated/riffer/params/any_of.rbs +4 -4
  94. data/sig/generated/riffer/params/boolean.rbs +1 -1
  95. data/sig/generated/riffer/params/param.rbs +28 -14
  96. data/sig/generated/riffer/params.rbs +20 -20
  97. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +12 -5
  98. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +50 -9
  99. data/sig/generated/riffer/providers/base.rbs +18 -0
  100. data/sig/generated/riffer/providers/deferred_tool_gateway/sink.rbs +23 -0
  101. data/sig/generated/riffer/providers/deferred_tool_gateway/tool.rbs +4 -0
  102. data/sig/generated/riffer/providers/deferred_tool_gateway.rbs +58 -0
  103. data/sig/generated/riffer/providers/mock.rbs +4 -0
  104. data/sig/generated/riffer/providers/open_ai.rbs +23 -6
  105. data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
  106. data/sig/generated/riffer/testing.rbs +4 -0
  107. data/sig/generated/riffer/tool.rbs +48 -2
  108. data/sig/generated/riffer/tools/response.rbs +9 -2
  109. data/sig/generated/riffer.rbs +3 -0
  110. data/sig/manual/riffer/deprecation.rbs +5 -0
  111. data/sig/manual/riffer/providers/deferred_tool_gateway.rbs +5 -0
  112. metadata +23 -3
  113. data/lib/riffer/tools/toolable.rb +0 -113
  114. data/sig/generated/riffer/tools/toolable.rbs +0 -66
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: bce35dc408dca35e5effe8987b7a8a43865720704f4c3c5f47e1c7709c733bb4
4
- data.tar.gz: 0edac840e1a65f7cf55ef5254ed6451b2c0aba469fed02fcb62eb4891970236f
3
+ metadata.gz: ab1324017f5d8669c50fc05d8c61af4a473a4b9d7fbb5e1a10e60f44d4028ed5
4
+ data.tar.gz: 1d50b24d3ae9cde461ccad3ecffd90554a94e4dec8d2664a4325d58b89fcb58c
5
5
  SHA512:
6
- metadata.gz: b23684154e93a57612c4de3b860336804ae3ccf265a951bcc71126bcc71d8f49de1e42331418187243ce846b88c47a4dcc20d52a196680f023c5ebb9da049b9d
7
- data.tar.gz: daaf1a51e35cd78605b82ddd11608713a0c1c2d231d8a7eae30d4048f0d60793e2c9a99aa5bbc3af6c48dd52f36ac095c860cdb7a665f39de319f6066182a1c0
6
+ metadata.gz: 9b07e31b31a5c129042f88a418d448e56c8e9d60805b8ff5221a509d7d0ea0cb1b197a459c865442df8595f2ee002c28e859c6943be8a88efa60e37ce3edc57f
7
+ data.tar.gz: 0d0b186db8324f5932a4913cf6e33cbcab16fa49fda3b9e2a3f5ad88cf626bacb4c29c1523c9e7a4a4f832244766fcf99935e83a1c8c910cb374fd6f063bf3d1
@@ -1,3 +1,3 @@
1
1
  {
2
- ".": "0.55.0"
2
+ ".": "0.57.0"
3
3
  }
data/CHANGELOG.md CHANGED
@@ -5,6 +5,43 @@ 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.57.0](https://github.com/janeapp/riffer/compare/riffer/v0.56.0...riffer/v0.57.0) (2026-11-13)
9
+
10
+
11
+ ### Features
12
+
13
+ * accept symbol param types and deprecate Ruby class types ([#572](https://github.com/janeapp/riffer/issues/572)) ([3aa722c](https://github.com/janeapp/riffer/commit/3aa722c170162c6f53b8374044806be20673dcb5))
14
+ * **agent:** add deferred tools that a tool can load partway through a run ([#557](https://github.com/janeapp/riffer/issues/557)) ([6ee3acb](https://github.com/janeapp/riffer/commit/6ee3acb4e38cae58eac5615ff0f77b876a4305b2))
15
+ * **anthropic:** continue pause_turn turns automatically ([#539](https://github.com/janeapp/riffer/issues/539)) ([b6fbedc](https://github.com/janeapp/riffer/commit/b6fbedce30475d1013e9c33bb5bad89dd4790d4b))
16
+ * **anthropic:** load deferred tools natively on anthropic and anthropic_vertex ([#575](https://github.com/janeapp/riffer/issues/575)) ([bba6541](https://github.com/janeapp/riffer/commit/bba65419f01163e9688b0dae75c863afd97bb5da))
17
+ * deprecate MCP client support ([#571](https://github.com/janeapp/riffer/issues/571)) ([0b031a4](https://github.com/janeapp/riffer/commit/0b031a4ecaf730a70d6fcfbb4dc1e2bca2014b0d))
18
+ * **evals:** deprecate Riffer::Evals and config.evals ([#573](https://github.com/janeapp/riffer/issues/573)) ([c66a0ba](https://github.com/janeapp/riffer/commit/c66a0bad842812521d9351f0257ab9cd1b701e20))
19
+ * **openai:** load deferred tools natively through additional_tools ([#576](https://github.com/janeapp/riffer/issues/576)) ([d57837f](https://github.com/janeapp/riffer/commit/d57837f9eb2d96c3f735b18bdf9ed9a198a3f2d9))
20
+ * **providers:** load deferred tools on any provider through a gateway tool ([#578](https://github.com/janeapp/riffer/issues/578)) ([92444fc](https://github.com/janeapp/riffer/commit/92444fc0ed35e0c3909f731628b686b2323ed8d8))
21
+
22
+
23
+ ### Bug Fixes
24
+
25
+ * **gemini:** encode namespaced tool names on the wire ([#582](https://github.com/janeapp/riffer/issues/582)) ([d78e911](https://github.com/janeapp/riffer/commit/d78e91120e7dcd1e197b6f3a7d0c57ba25d48cbd))
26
+
27
+ ## [0.56.0](https://github.com/janeapp/riffer/compare/riffer/v0.55.0...riffer/v0.56.0) (2026-11-09)
28
+
29
+
30
+ ### ⚠ BREAKING CHANGES
31
+
32
+ * **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`.
33
+
34
+ ### Features
35
+
36
+ * add Riffer::Deprecation for deprecation warnings ([#549](https://github.com/janeapp/riffer/issues/549)) ([6ad6046](https://github.com/janeapp/riffer/commit/6ad604647de1074d4f3f0739727940bcf06667fd))
37
+ * 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))
38
+ * **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))
39
+
40
+
41
+ ### Bug Fixes
42
+
43
+ * **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))
44
+
8
45
  ## [0.55.0](https://github.com/janeapp/riffer/compare/riffer/v0.54.0...riffer/v0.55.0) (2026-10-29)
9
46
 
10
47
 
data/README.md CHANGED
@@ -60,9 +60,10 @@ Comprehensive guides live at [riffer.ai](https://riffer.ai):
60
60
  - [Evals](https://riffer.ai/guides/evals/) - Evaluating agent quality
61
61
  - [Guardrails](https://riffer.ai/guides/guardrails/) - Input/output validation
62
62
  - [Skills](https://riffer.ai/guides/skills/) - Packaged agent capabilities
63
- - [MCP](https://riffer.ai/guides/mcp/) - Integrating third-party MCP servers
63
+ - [MCP](https://riffer.ai/guides/mcp/) - Integrating third-party MCP servers (deprecated)
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/AGENTS.md CHANGED
@@ -124,9 +124,64 @@ class MyAgent < Riffer::Agent
124
124
  end
125
125
  ```
126
126
 
127
- ### use_mcp
127
+ ### deferred_tools (experimental)
128
128
 
129
- Loads tools from registered [MCP](MCP.md) servers by tag.
129
+ Holds tools back from the model until one of the agent's own tools loads them. Every tool you pass to `uses_tools` costs tokens on every request, and models pick tools less reliably from a long list, so defer the ones most turns don't need:
130
+
131
+ ```ruby
132
+ class Assistant < Riffer::Agent
133
+ model 'mock/riffer-1'
134
+ instructions "If you need a tool you don't have, use find_tools."
135
+
136
+ uses_tools [GetWeather, FindTools, ConnectCalendar]
137
+ deferred_tools [ListEvents, CreateEvent, SendInvoice]
138
+ end
139
+ ```
140
+
141
+ Like `uses_tools`, `deferred_tools` takes an Array or a lambda that receives the context:
142
+
143
+ ```ruby
144
+ deferred_tools ->(context) { context[:billing] ? [ListEvents, SendInvoice] : [ListEvents] }
145
+ ```
146
+
147
+ A tool can't be both: one that's in `uses_tools` (or comes from skills or MCP) and in `deferred_tools` raises `Riffer::ArgumentError` when the agent is built. The resolved list is `agent.deferred_tools`, and tools read it at call time as `context.deferred_tools`.
148
+
149
+ Any tool loads deferred tools by returning `load_tools(...)`; see [Tools → Loading deferred tools](TOOLS.md#loading-deferred-tools-experimental). Riffer records each load in the conversation, so a loaded tool stays loaded for the rest of it, including after the agent and its session are [serialized](SERIALIZATION.md) and restored. A call to a deferred tool that hasn't been loaded is refused.
150
+
151
+ By default deferred tools load natively, which needs provider support. `anthropic` and `anthropic_vertex` (see [Anthropic → Deferred Tools](providers/ANTHROPIC.md#deferred-tools)), [OpenAI](providers/OPENAI.md#deferred-tools-experimental) and [Azure OpenAI](providers/AZURE_OPENAI.md#deferred-tools-experimental) load them natively, and the [Mock provider](providers/MOCK_PROVIDER.md) does too, for tests. Building an agent with deferred tools on any other provider raises `Riffer::ArgumentError` naming the provider, unless it uses the [gateway strategy](#deferred-tools-strategy-experimental). Riffer doesn't check which models support native loading, so an unsupported model on one of those providers gets the provider's own error.
152
+
153
+ Nothing tells the model that more tools exist unless you do, in a tool's description or the instructions. If no tool ever returns `load_tools`, the deferred tools can't be reached, and riffer can't detect that.
154
+
155
+ Deferring a tool hides it from the model; it doesn't restrict it. Any tool can load any deferred tool, so leave a tool out of the agent entirely if the user mustn't reach it.
156
+
157
+ The feature is **experimental**: it can change in any minor release (see [Stability](STABILITY.md#experimental-features)).
158
+
159
+ #### Deferred tools strategy (experimental)
160
+
161
+ By default the provider loads deferred tools itself. For a provider without native loading, or a model that rejects it, opt the agent into the **experimental** gateway strategy:
162
+
163
+ ```ruby
164
+ class Assistant < Riffer::Agent
165
+ model 'amazon_bedrock/my-model'
166
+ instructions "If you need a tool you don't have, use find_tools."
167
+
168
+ uses_tools [FindTools]
169
+ deferred_tools [ListEvents, CreateEvent], strategy: :gateway
170
+ end
171
+ ```
172
+
173
+ With `strategy: :gateway`, the provider never loads deferred tools natively, even one that can. Every request carries one extra tool, the gateway, and the model calls a loaded tool through it, so the tool list never changes and a load keeps the prompt cache; see [Tools → The gateway strategy](TOOLS.md#the-gateway-strategy). No other tool of the agent can share the gateway's name.
174
+
175
+ | Strategy | Behavior |
176
+ | ------------------- | ------------------------------------------------------------------------------------------- |
177
+ | `:native` (default) | The provider loads deferred tools itself; raises on a provider without native loading |
178
+ | `:gateway` | Loaded tools are called through one extra tool, on every provider; experimental, may change |
179
+
180
+ Riffer does not pick a strategy per provider — the choice is always yours. The strategy is copied to subclasses and survives [serialization](SERIALIZATION.md). An unknown value raises `Riffer::ArgumentError`. `strategy:` can also be passed with a lambda: `deferred_tools ->(context) { [ListEvents] }, strategy: :gateway`.
181
+
182
+ ### use_mcp (deprecated)
183
+
184
+ Loads tools from registered [MCP](MCP.md) servers by tag. MCP client support is deprecated and will be removed in a future release; each `use_mcp` line reports a [deprecation](CONFIGURATION.md#deprecations). See [MCP → Moving off MCP](MCP.md#moving-off-mcp).
130
185
 
131
186
  ### model_options
132
187
 
@@ -174,9 +229,9 @@ class SentimentAgent < Riffer::Agent
174
229
  model 'openai/gpt-5-mini'
175
230
  instructions 'Analyze the sentiment of the given text.'
176
231
  structured_output do
177
- required :sentiment, String, description: "positive, negative, or neutral"
178
- required :score, Float, description: "Confidence score between 0 and 1"
179
- optional :explanation, String, description: "Brief explanation"
232
+ required :sentiment, :string, description: "positive, negative, or neutral"
233
+ required :score, :number, description: "Confidence score between 0 and 1"
234
+ optional :explanation, :string, description: "Brief explanation"
180
235
  end
181
236
  end
182
237
  ```
@@ -207,12 +262,12 @@ class SentimentAgent < Riffer::Agent
207
262
  model 'amazon_bedrock/my-model'
208
263
  instructions 'Analyze the sentiment of the given text.'
209
264
  structured_output strategy: :prompted do
210
- required :sentiment, String, description: "positive, negative, or neutral"
265
+ required :sentiment, :string, description: "positive, negative, or neutral"
211
266
  end
212
267
  end
213
268
  ```
214
269
 
215
- With `strategy: :prompted`, the provider never receives its native structured-output field. Instead, an instruction is appended to the end of every user message on every request of the run, after consecutive user messages are merged (it is not stored in `session.messages`, and the system instructions are left untouched). The instruction carries the JSON Schema, an example of the expected shape with placeholder values (`"<string>"`, enum values as `"a | b"`, an `AnyOf` field as its first variant, or as `"<integer> | <string>"` when every variant is primitive), and a nudge to reply with the JSON right away unless the request needs a tool. The reply is parsed and validated exactly as above: `response.content` is the reply's JSON text, `response.structured_output` holds the validated object, and a reply that fails parsing or validation ends with `:invalid_structured_output`. Because nothing forces the model to comply, expect more `:invalid_structured_output` outcomes than with the native strategy.
270
+ With `strategy: :prompted`, the provider never receives its native structured-output field. Instead, an instruction is appended to the end of every user message on every request of the run, after consecutive user messages are merged (it is not stored in `session.messages`, and the system instructions are left untouched). The instruction carries the JSON Schema, an example of the expected shape with placeholder values (`"<string>"`, enum values as `"a | b"`, an `:any_of` field as its first variant, or as `"<integer> | <string>"` when every variant is primitive), and a nudge to reply with the JSON right away unless the request needs a tool. The reply is parsed and validated exactly as above: `response.content` is the reply's JSON text, `response.structured_output` holds the validated object, and a reply that fails parsing or validation ends with `:invalid_structured_output`. Because nothing forces the model to comply, expect more `:invalid_structured_output` outcomes than with the native strategy.
216
271
 
217
272
  | Strategy | Behavior |
218
273
  | ------------------- | --------------------------------------------------------------- |
@@ -223,15 +278,15 @@ Riffer does not pick a strategy per model — the choice is always yours. The st
223
278
 
224
279
  #### Nested Objects
225
280
 
226
- Use `Hash` with a block to define nested object schemas:
281
+ Use `:object` with a block to define nested object schemas:
227
282
 
228
283
  ```ruby
229
284
  structured_output do
230
- required :name, String, description: "Person name"
231
- required :address, Hash, description: "Mailing address" do
232
- required :street, String, description: "Street address"
233
- required :city, String, description: "City"
234
- optional :postal_code, String, description: "Postal or zip code"
285
+ required :name, :string, description: "Person name"
286
+ required :address, :object, description: "Mailing address" do
287
+ required :street, :string, description: "Street address"
288
+ required :city, :string, description: "City"
289
+ optional :postal_code, :string, description: "Postal or zip code"
235
290
  end
236
291
  end
237
292
  ```
@@ -240,22 +295,22 @@ Validation errors use dot-path notation: `address.city is required`.
240
295
 
241
296
  #### Typed Arrays
242
297
 
243
- Use `Array` with the `of:` keyword for arrays of primitive types:
298
+ Use `:array` with the `of:` keyword for arrays of primitive types:
244
299
 
245
300
  ```ruby
246
301
  structured_output do
247
- required :tags, Array, of: String, description: "Tags"
248
- required :scores, Array, of: Float, description: "Scores"
302
+ required :tags, :array, of: :string, description: "Tags"
303
+ required :scores, :array, of: :number, description: "Scores"
249
304
  end
250
305
  ```
251
306
 
252
- `of:` takes a primitive type: `String`, `Integer`, `Float`, `Riffer::Params::Boolean`, `TrueClass`, `FalseClass`.
307
+ `of:` takes a primitive type: `:string`, `:integer`, `:number` or `:boolean`.
253
308
 
254
309
  Add `enum:` to limit each item to a list of values:
255
310
 
256
311
  ```ruby
257
312
  structured_output do
258
- required :tags, Array, of: String, enum: %w[urgent billing technical]
313
+ required :tags, :array, of: :string, enum: %w[urgent billing technical]
259
314
  end
260
315
  ```
261
316
 
@@ -265,8 +320,8 @@ For an array of arrays, put the type in brackets. Each pair of brackets adds a l
265
320
 
266
321
  ```ruby
267
322
  structured_output do
268
- required :rows, Array, of: [Integer], description: "Seat numbers, one array per row"
269
- required :board, Array, of: [String], enum: %w[x o]
323
+ required :rows, :array, of: [:integer], description: "Seat numbers, one array per row"
324
+ required :board, :array, of: [:string], enum: %w[x o]
270
325
  end
271
326
  ```
272
327
 
@@ -274,13 +329,13 @@ A row that isn't an array fails validation with its index: `rows[1] must be an a
274
329
 
275
330
  #### Formats
276
331
 
277
- Use `format:` on a `String`, or on an `Array` whose innermost type is `String`, to require a standard string format:
332
+ Use `format:` on a `:string`, or on an `:array` whose innermost type is `:string`, to require a standard string format:
278
333
 
279
334
  ```ruby
280
335
  structured_output do
281
- required :born_on, String, format: "date"
282
- optional :email, String, format: "email"
283
- required :visit_ids, Array, of: String, format: "uuid"
336
+ required :born_on, :string, format: "date"
337
+ optional :email, :string, format: "email"
338
+ required :visit_ids, :array, of: :string, format: "uuid"
284
339
  end
285
340
  ```
286
341
 
@@ -292,14 +347,14 @@ A model that must match a format writes a matching value even when it has none,
292
347
 
293
348
  #### Arrays of Objects
294
349
 
295
- Use `Array` with a block to define arrays of objects:
350
+ Use `:array` with a block to define arrays of objects:
296
351
 
297
352
  ```ruby
298
353
  structured_output do
299
- required :items, Array, description: "Line items" do
300
- required :name, String, description: "Product name"
301
- required :price, Float, description: "Price"
302
- optional :quantity, Integer, description: "Quantity"
354
+ required :items, :array, description: "Line items" do
355
+ required :name, :string, description: "Product name"
356
+ required :price, :number, description: "Price"
357
+ optional :quantity, :integer, description: "Quantity"
303
358
  end
304
359
  end
305
360
  ```
@@ -312,12 +367,12 @@ Blocks can be nested arbitrarily deep:
312
367
 
313
368
  ```ruby
314
369
  structured_output do
315
- required :orders, Array, description: "Orders" do
316
- required :id, String, description: "Order ID"
317
- required :shipping, Hash, description: "Shipping info" do
318
- required :address, Hash, description: "Address" do
319
- required :street, String
320
- required :city, String
370
+ required :orders, :array, description: "Orders" do
371
+ required :id, :string, description: "Order ID"
372
+ required :shipping, :object, description: "Shipping info" do
373
+ required :address, :object, description: "Address" do
374
+ required :street, :string
375
+ required :city, :string
321
376
  end
322
377
  end
323
378
  end
@@ -326,18 +381,18 @@ end
326
381
 
327
382
  #### Either/Or Shapes
328
383
 
329
- Use `Riffer::Params::AnyOf` when a field must be one of several object shapes. Each `variant` block defines one shape, the same way a `Hash` block does:
384
+ Use `:any_of` when a field must be one of several object shapes. Each `variant` block defines one shape, the same way an `:object` block does:
330
385
 
331
386
  ```ruby
332
387
  structured_output do
333
- required :result, Riffer::Params::AnyOf, description: "The address, or why none was found" do
388
+ required :result, :any_of, description: "The address, or why none was found" do
334
389
  variant do
335
- required :street, String, description: "Street address"
336
- required :city, String, description: "City"
390
+ required :street, :string, description: "Street address"
391
+ required :city, :string, description: "City"
337
392
  end
338
393
  variant do
339
- required :error_code, String, enum: %w[no_address multiple_addresses]
340
- required :error_message, String
394
+ required :error_code, :string, enum: %w[no_address multiple_addresses]
395
+ required :error_message, :string
341
396
  end
342
397
  end
343
398
  end
@@ -345,19 +400,19 @@ end
345
400
 
346
401
  The schema sends the field as `anyOf`, with one object per variant. An answer must match one variant completely: every required field of that variant, and no field from outside it. Variants are tried in order and the first match is returned. When none match, the error lists each variant's problems: `result must match one of the variants: variant 1 (street is required, city is required), variant 2 (error_code is required, error_message is required)`.
347
402
 
348
- An optional `AnyOf` field can also be `null`.
403
+ An optional `:any_of` field can also be `null`.
349
404
 
350
405
  A variant can be a primitive type instead of a block, with its own `description:`, `enum:` or `format:`, and one field can mix both kinds:
351
406
 
352
407
  ```ruby
353
408
  structured_output do
354
- required :quantity, Riffer::Params::AnyOf, description: "A count, or a word like 'several'" do
355
- variant Integer
356
- variant String
409
+ required :quantity, :any_of, description: "A count, or a word like 'several'" do
410
+ variant :integer
411
+ variant :string
357
412
  end
358
- optional :due, Riffer::Params::AnyOf do
359
- variant String, format: "date"
360
- variant String, enum: ["none"]
413
+ optional :due, :any_of do
414
+ variant :string, format: "date"
415
+ variant :string, enum: ["none"]
361
416
  end
362
417
  end
363
418
  ```
@@ -366,9 +421,9 @@ Each primitive variant is sent as its own `anyOf` branch. A value whose type mat
366
421
 
367
422
  #### Limitations
368
423
 
369
- Anthropic and Bedrock reject a structured output schema with more than 16 union-type fields. Every `AnyOf` field counts, and so does every optional field, since strict mode sends it as nullable.
424
+ Anthropic and Bedrock reject a structured output schema with more than 16 union-type fields. Every `:any_of` field counts, and so does every optional field, since strict mode sends it as nullable.
370
425
 
371
- A `Hash` param requires a block, and an `Array` param requires a block or `of:`. Using both `of:` and a block raises `Riffer::ArgumentError`. Using `of:` with a non-primitive type (e.g. `of: Hash` or `of: [Hash]`), or with more than one type (`of: [Integer, String]`), also raises `Riffer::ArgumentError`. An `AnyOf` param requires a block with at least two `variant`s, and can't be used with `of:` or `enum:`. A `variant` takes either a primitive type, with optional `description:`, `enum:` or `format:`, or a block. Anything else raises `Riffer::ArgumentError`, and so does an `Integer` variant after a `Float` variant without `enum:`, since that `Float` variant accepts every number and the first match wins. Using `enum:` on a `Hash`, or on an `Array` without `of:`, also raises `Riffer::ArgumentError`. So does `format:` with an unsupported format, on a type other than `String` or an `Array` whose innermost type is `String`, or together with `enum:`.
426
+ An `:object` param requires a block, and an `:array` param requires a block or `of:`. Using both `of:` and a block raises `Riffer::ArgumentError`. Using `of:` with a non-primitive type (e.g. `of: :object` or `of: [:object]`), or with more than one type (`of: [:integer, :string]`), also raises `Riffer::ArgumentError`. An `:any_of` param requires a block with at least two `variant`s, and can't be used with `of:` or `enum:`. A `variant` takes either a primitive type, with optional `description:`, `enum:` or `format:`, or a block. Anything else raises `Riffer::ArgumentError`, and so does an `:integer` variant after a `:number` variant without `enum:`, since that `:number` variant accepts every number and the first match wins. Using `enum:` on an `:object`, or on an `:array` without `of:`, also raises `Riffer::ArgumentError`. So does `format:` with an unsupported format, on a type other than `:string` or an `:array` whose innermost type is `:string`, or together with `enum:`.
372
427
 
373
428
  Structured output is not compatible with streaming — calling `stream` on an agent with structured output configured raises `Riffer::ArgumentError`.
374
429
 
@@ -9,7 +9,7 @@ Agent.new(session: nil, context: nil)
9
9
  ```
10
10
 
11
11
  - **`session:`** — an existing `Riffer::Agent::Session`. When given, the agent uses it as-is (no system/skills seeding). Typical use case: cross-process resume from persisted history. A provided session is repaired at construction time so the `tool_use` ↔ `tool_result` invariant holds before the next inference call: orphaned `tool_use` exchanges (an assistant `tool_call` with no matching `Tool` result) and parentless `Tool` messages are dropped. Pending tool calls on the **resume boundary** — the last assistant whose tail is purely `Tool` results (or none) — are preserved so `generate`/`stream` can execute them.
12
- - **`context:`** — a `Hash` carried for the lifetime of the agent. Used to evaluate Proc-based `instructions`, `model`, `uses_tools`, and skill activation at construction time, and threaded through tool execution and guardrails on every `generate`/`stream` call.
12
+ - **`context:`** — a `Hash` carried for the lifetime of the agent. Used to evaluate Proc-based `instructions`, `model`, `uses_tools`, `deferred_tools`, and skill activation at construction time, and threaded through tool execution and guardrails on every `generate`/`stream` call.
13
13
 
14
14
  When `session:` is omitted, the agent constructs a fresh session and seeds it with `[instruction_message, skills_message].compact` eagerly. To swap context, construct a new agent — context is fixed for the lifetime of an agent instance.
15
15
 
@@ -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).
@@ -133,7 +133,9 @@ Streaming is tested with the default `net_http` adapter.
133
133
  - A non-success status raises `Riffer::APIError` (a `Riffer::Error`). `status` holds the HTTP status (`nil` for an error event inside a stream) and `body` the raw response text.
134
134
  - Transport failures are raised as Faraday's own errors, such as `Faraday::TimeoutError` and `Faraday::ConnectionFailed` (both `Faraday::Error`s).
135
135
 
136
- ### MCP (Model Context Protocol)
136
+ ### MCP (deprecated)
137
+
138
+ `config.mcp` is deprecated and will be removed with MCP client support in a future release; each line that sets `credentials` or `discovery_runner` reports a [deprecation](#deprecations). See [MCP → Moving off MCP](MCP.md#moving-off-mcp).
137
139
 
138
140
  Optional settings for [MCP server integrations](MCP.md):
139
141
 
@@ -152,7 +154,9 @@ end
152
154
 
153
155
  See [MCP](MCP.md) for registration, tags, and agent `use_mcp`.
154
156
 
155
- ### Evals
157
+ ### Evals (deprecated)
158
+
159
+ `config.evals` is deprecated and will move out of riffer into the `riffer-evals` gem along with [evals](EVALS.md). Reading it reports a [deprecation](#deprecations).
156
160
 
157
161
  ```ruby
158
162
  Riffer.configure do |config|
@@ -276,7 +280,7 @@ See [Model Catalog](CATALOG.md) for the file format, lookup, layering, and valid
276
280
 
277
281
  ### Pricing (deprecated)
278
282
 
279
- `config.pricing` is deprecated and will be removed in a future release. Move rates into a [catalog file](CATALOG.md#pricing); the first `set` call prints a deprecation warning. Riffer still reads these rates as a fallback, and catalog pricing wins when both price a model.
283
+ `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
284
 
281
285
  ```ruby
282
286
  # before
@@ -291,6 +295,53 @@ end
291
295
 
292
296
  `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
297
 
298
+ ### Deprecations
299
+
300
+ 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:
301
+
302
+ ```
303
+ riffer: config.pricing is deprecated and will be removed in a future version; move rates into a catalog file listed in config.catalog_files (see docs/CATALOG.md). Called from config/initializers/riffer.rb:4.
304
+ ```
305
+
306
+ `config.deprecations` decides what happens:
307
+
308
+ ```ruby
309
+ Riffer.configure do |config|
310
+ config.deprecations = ->(event) { Rails.logger.warn(event.to_s) }
311
+ end
312
+ ```
313
+
314
+ | Value | Description |
315
+ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
316
+ | `:warn` (default) | Prints the report to stderr with `Kernel.warn`, once per deprecation per calling line. |
317
+ | `:raise` | Raises `Riffer::DeprecationError` on every call, so a test suite fails on each test that makes one. See [Testing — Deprecations](TESTING.md#deprecations). |
318
+ | `:silence` | Reports nothing. |
319
+ | 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. |
320
+
321
+ Any other value raises `Riffer::ArgumentError`.
322
+
323
+ ### Future flags
324
+
325
+ `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:
326
+
327
+ ```ruby
328
+ Riffer.configure do |config|
329
+ config.future.some_flag = true
330
+ end
331
+ ```
332
+
333
+ 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`.
334
+
335
+ A flag goes through three stages:
336
+
337
+ 1. **Opt-in.** The flag is off by default, and setting it to `true` turns the new behaviour on.
338
+ 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.
339
+ 3. **Removed.** A release later the flag is gone, and setting it raises `NoMethodError`.
340
+
341
+ | Flag | Stage | Description |
342
+ | -------- | ----- | ------------------------------- |
343
+ | _(none)_ | | Riffer has no future flags yet. |
344
+
294
345
  ### Message ID Strategy
295
346
 
296
347
  Opt in to stable identifiers on every message for logging, persistence, or replay:
data/docs/EVALS.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # Evals
2
2
 
3
+ > **Deprecated:** evals will move out of riffer into a separate `riffer-evals` gem that keeps the `Riffer::Evals` API. Until then, using `Riffer::Evals` or `config.evals` reports a [deprecation](STABILITY.md#deprecations) warning.
4
+
3
5
  Evals let you measure the quality of agent outputs using LLM-as-judge evaluations.
4
6
 
5
7
  ## When to Use Evals
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/MCP.md CHANGED
@@ -1,7 +1,43 @@
1
1
  # MCP
2
2
 
3
+ > **Deprecated:** MCP client support is deprecated and will be removed in a future breaking release. Nothing replaces it in that release, but an MCP integration built on the new hooks system ([#534](https://github.com/janeapp/riffer/issues/534)) may follow later. `use_mcp`, `Riffer::Mcp.register` and the `config.mcp` setters each report a [deprecation](CONFIGURATION.md#deprecations) that names the line in your code that made the call. To find every call before the upgrade, run your suite with [deprecations raising](TESTING.md#deprecations). See [Moving off MCP](#moving-off-mcp) for what to use instead.
4
+
3
5
  Riffer can consume third-party [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers as tool sources. Tools are discovered automatically at registration time — no handwritten Ruby per tool required.
4
6
 
7
+ ## Moving off MCP
8
+
9
+ To hold tools back from the model until it asks for them, the way progressive discovery does, use [deferred tools](AGENTS.md#deferred_tools-experimental).
10
+
11
+ To keep calling an MCP server, wrap the [`mcp`](https://github.com/modelcontextprotocol/ruby-sdk) gem in your own [`Riffer::Tool`](TOOLS.md) and list it with `uses_tools`. Headers you build from `context` take the place of the `config.mcp.credentials` callback:
12
+
13
+ ```ruby
14
+ # Gemfile: gem "mcp"
15
+ require "mcp"
16
+
17
+ class CreateIssueTool < Riffer::Tool
18
+ description "Creates a GitHub issue"
19
+
20
+ params do
21
+ required :title, :string, description: "The issue title"
22
+ optional :body, :string, description: "The issue body"
23
+ end
24
+
25
+ def call(context:, title:, body: nil)
26
+ transport = MCP::Client::HTTP.new(
27
+ url: "https://mcp.github.com",
28
+ headers: { "Authorization" => "Bearer #{context[:github_token]}" }
29
+ )
30
+ client = MCP::Client.new(transport: transport)
31
+ result = client.call_tool(name: "create_issue", arguments: { title: title, body: body }.compact).fetch("result")
32
+ content = result["content"].filter_map { |item| item["text"] }.join
33
+
34
+ result["isError"] ? error(content) : text(content)
35
+ end
36
+ end
37
+ ```
38
+
39
+ A JSON-RPC error raises `MCP::Client::ServerError` from `call_tool`.
40
+
5
41
  ## Overview
6
42
 
7
43
  1. Register an MCP server globally with `Riffer::Mcp.register`.