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.
- checksums.yaml +4 -4
- data/.release-please-manifest.json +1 -1
- data/CHANGELOG.md +37 -0
- data/README.md +3 -2
- data/UPGRADING.md +3 -0
- data/docs/AGENTS.md +105 -50
- data/docs/AGENT_LIFECYCLE.md +2 -2
- data/docs/CONFIGURATION.md +54 -3
- data/docs/EVALS.md +2 -0
- data/docs/GUARDRAILS.md +2 -0
- data/docs/MCP.md +36 -0
- data/docs/MESSAGES.md +125 -15
- data/docs/OVERVIEW.md +7 -7
- data/docs/SERIALIZATION.md +12 -2
- data/docs/SKILLS.md +1 -1
- data/docs/STABILITY.md +32 -0
- data/docs/STREAM_EVENTS.md +16 -0
- data/docs/TESTING.md +22 -1
- data/docs/TOOLS.md +93 -37
- data/docs/TOOL_ADVANCED.md +7 -0
- data/docs/providers/AMAZON_BEDROCK.md +7 -3
- data/docs/providers/ANTHROPIC.md +53 -16
- data/docs/providers/AZURE_OPENAI.md +9 -3
- data/docs/providers/CUSTOM_PROVIDERS.md +43 -0
- data/docs/providers/GEMINI.md +9 -5
- data/docs/providers/GOOGLE_CLOUD.md +10 -5
- data/docs/providers/MOCK_PROVIDER.md +4 -0
- data/docs/providers/OPENAI.md +28 -4
- data/docs/providers/OPENROUTER.md +11 -3
- data/docs/providers/PROVIDERS.md +1 -1
- data/docs-site/index.html.erb +1 -1
- data/docs-site/manifest.yml +3 -0
- data/lib/riffer/agent/config.rb +21 -0
- data/lib/riffer/agent/context.rb +36 -18
- data/lib/riffer/agent/run.rb +82 -21
- data/lib/riffer/agent/serializer.rb +5 -0
- data/lib/riffer/agent/session.rb +34 -10
- data/lib/riffer/agent.rb +43 -0
- data/lib/riffer/config/future.rb +53 -0
- data/lib/riffer/config/mcp.rb +17 -0
- data/lib/riffer/config/pricing.rb +5 -15
- data/lib/riffer/config.rb +28 -1
- data/lib/riffer/deprecation/event.rb +25 -0
- data/lib/riffer/deprecation.rb +60 -0
- data/lib/riffer/evals/evaluator.rb +8 -1
- data/lib/riffer/evals/evaluator_runner.rb +1 -0
- data/lib/riffer/evals/judge.rb +2 -2
- data/lib/riffer/evals.rb +2 -0
- data/lib/riffer/mcp/search_tool.rb +1 -1
- data/lib/riffer/mcp.rb +7 -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/messages/tool.rb +6 -2
- data/lib/riffer/params/any_of.rb +5 -8
- data/lib/riffer/params/boolean.rb +1 -1
- data/lib/riffer/params/param.rb +96 -67
- data/lib/riffer/params.rb +50 -71
- data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +28 -11
- data/lib/riffer/providers/anthropic_compatible/messages_api.rb +136 -38
- data/lib/riffer/providers/base.rb +57 -12
- data/lib/riffer/providers/deferred_tool_gateway/sink.rb +54 -0
- data/lib/riffer/providers/deferred_tool_gateway/tool.rb +17 -0
- data/lib/riffer/providers/deferred_tool_gateway.rb +150 -0
- data/lib/riffer/providers/gemini.rb +5 -5
- data/lib/riffer/providers/mock.rb +6 -0
- data/lib/riffer/providers/open_ai.rb +59 -26
- data/lib/riffer/skills/activate_tool.rb +1 -1
- data/lib/riffer/stream_events/server_tool_done.rb +21 -0
- data/lib/riffer/testing.rb +6 -0
- data/lib/riffer/tool.rb +92 -2
- data/lib/riffer/tools/response.rb +11 -2
- data/lib/riffer/version.rb +1 -1
- data/lib/riffer.rb +2 -0
- data/sig/generated/riffer/agent/config.rbs +13 -1
- data/sig/generated/riffer/agent/context.rbs +16 -0
- data/sig/generated/riffer/agent/run.rbs +19 -2
- data/sig/generated/riffer/agent/session.rbs +6 -0
- data/sig/generated/riffer/agent.rbs +13 -0
- data/sig/generated/riffer/config/future.rbs +29 -0
- data/sig/generated/riffer/config/mcp.rbs +7 -0
- data/sig/generated/riffer/config/pricing.rbs +0 -9
- data/sig/generated/riffer/config.rbs +13 -1
- data/sig/generated/riffer/deprecation/event.rbs +17 -0
- data/sig/generated/riffer/deprecation.rbs +27 -0
- data/sig/generated/riffer/evals/evaluator.rbs +4 -0
- data/sig/generated/riffer/evals.rbs +1 -0
- data/sig/generated/riffer/mcp.rbs +1 -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/messages/tool.rbs +4 -2
- data/sig/generated/riffer/params/any_of.rbs +4 -4
- data/sig/generated/riffer/params/boolean.rbs +1 -1
- data/sig/generated/riffer/params/param.rbs +28 -14
- data/sig/generated/riffer/params.rbs +20 -20
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +12 -5
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +50 -9
- data/sig/generated/riffer/providers/base.rbs +18 -0
- data/sig/generated/riffer/providers/deferred_tool_gateway/sink.rbs +23 -0
- data/sig/generated/riffer/providers/deferred_tool_gateway/tool.rbs +4 -0
- data/sig/generated/riffer/providers/deferred_tool_gateway.rbs +58 -0
- data/sig/generated/riffer/providers/mock.rbs +4 -0
- data/sig/generated/riffer/providers/open_ai.rbs +23 -6
- data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
- data/sig/generated/riffer/testing.rbs +4 -0
- data/sig/generated/riffer/tool.rbs +48 -2
- data/sig/generated/riffer/tools/response.rbs +9 -2
- data/sig/generated/riffer.rbs +3 -0
- data/sig/manual/riffer/deprecation.rbs +5 -0
- data/sig/manual/riffer/providers/deferred_tool_gateway.rbs +5 -0
- metadata +23 -3
- data/lib/riffer/tools/toolable.rb +0 -113
- data/sig/generated/riffer/tools/toolable.rbs +0 -66
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: ab1324017f5d8669c50fc05d8c61af4a473a4b9d7fbb5e1a10e60f44d4028ed5
|
|
4
|
+
data.tar.gz: 1d50b24d3ae9cde461ccad3ecffd90554a94e4dec8d2664a4325d58b89fcb58c
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 9b07e31b31a5c129042f88a418d448e56c8e9d60805b8ff5221a509d7d0ea0cb1b197a459c865442df8595f2ee002c28e859c6943be8a88efa60e37ce3edc57f
|
|
7
|
+
data.tar.gz: 0d0b186db8324f5932a4913cf6e33cbcab16fa49fda3b9e2a3f5ad88cf626bacb4c29c1523c9e7a4a4f832244766fcf99935e83a1c8c910cb374fd6f063bf3d1
|
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
|
-
###
|
|
127
|
+
### deferred_tools (experimental)
|
|
128
128
|
|
|
129
|
-
|
|
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,
|
|
178
|
-
required :score,
|
|
179
|
-
optional :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,
|
|
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 `
|
|
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 `
|
|
281
|
+
Use `:object` with a block to define nested object schemas:
|
|
227
282
|
|
|
228
283
|
```ruby
|
|
229
284
|
structured_output do
|
|
230
|
-
required :name,
|
|
231
|
-
required :address,
|
|
232
|
-
required :street,
|
|
233
|
-
required :city,
|
|
234
|
-
optional :postal_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 `
|
|
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,
|
|
248
|
-
required :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:
|
|
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,
|
|
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,
|
|
269
|
-
required :board,
|
|
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
|
|
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,
|
|
282
|
-
optional :email,
|
|
283
|
-
required :visit_ids,
|
|
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 `
|
|
350
|
+
Use `:array` with a block to define arrays of objects:
|
|
296
351
|
|
|
297
352
|
```ruby
|
|
298
353
|
structured_output do
|
|
299
|
-
required :items,
|
|
300
|
-
required :name,
|
|
301
|
-
required :price,
|
|
302
|
-
optional :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,
|
|
316
|
-
required :id,
|
|
317
|
-
required :shipping,
|
|
318
|
-
required :address,
|
|
319
|
-
required :street,
|
|
320
|
-
required :city,
|
|
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 `
|
|
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,
|
|
388
|
+
required :result, :any_of, description: "The address, or why none was found" do
|
|
334
389
|
variant do
|
|
335
|
-
required :street,
|
|
336
|
-
required :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,
|
|
340
|
-
required :error_message,
|
|
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 `
|
|
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,
|
|
355
|
-
variant
|
|
356
|
-
variant
|
|
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,
|
|
359
|
-
variant
|
|
360
|
-
variant
|
|
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 `
|
|
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
|
-
|
|
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
|
|
data/docs/AGENT_LIFECYCLE.md
CHANGED
|
@@ -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).
|
data/docs/CONFIGURATION.md
CHANGED
|
@@ -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 (
|
|
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);
|
|
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`.
|