riffer 0.54.0 → 0.56.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.claude/rules/rbs-inline.md +6 -6
- data/.release-please-manifest.json +1 -1
- data/.ruby-version +1 -1
- data/CHANGELOG.md +46 -0
- data/README.md +26 -1
- data/Steepfile +2 -2
- data/UPGRADING.md +3 -0
- data/docs/AGENTS.md +37 -12
- data/docs/AGENT_LIFECYCLE.md +1 -1
- data/docs/CATALOG.md +8 -8
- data/docs/CONFIGURATION.md +95 -17
- data/docs/GUARDRAILS.md +2 -0
- data/docs/MCP.md +3 -4
- data/docs/MESSAGES.md +112 -15
- data/docs/STABILITY.md +32 -0
- data/docs/STREAM_EVENTS.md +17 -1
- data/docs/TESTING.md +22 -1
- data/docs/TOOLS.md +11 -11
- data/docs/TRACING.md +1 -1
- data/docs/providers/AMAZON_BEDROCK.md +3 -1
- data/docs/providers/ANTHROPIC.md +44 -44
- data/docs/providers/CUSTOM_PROVIDERS.md +59 -0
- data/docs/providers/GEMINI.md +76 -26
- data/docs/providers/GOOGLE_CLOUD.md +363 -0
- data/docs/providers/MOCK_PROVIDER.md +2 -0
- data/docs/providers/OPENAI.md +3 -1
- data/docs/providers/PROVIDERS.md +30 -18
- data/docs-site/manifest.yml +6 -0
- data/lib/riffer/agent/run.rb +28 -13
- data/lib/riffer/agent/session.rb +33 -10
- data/lib/riffer/agent/structured_output.rb +6 -1
- data/lib/riffer/config/anthropic.rb +9 -0
- data/lib/riffer/config/future.rb +53 -0
- data/lib/riffer/config/gemini.rb +9 -0
- data/lib/riffer/config/google_cloud.rb +38 -0
- data/lib/riffer/config/pricing.rb +5 -15
- data/lib/riffer/config.rb +19 -0
- data/lib/riffer/deprecation/event.rb +25 -0
- data/lib/riffer/deprecation.rb +60 -0
- data/lib/riffer/http/client.rb +141 -0
- data/lib/riffer/http.rb +5 -0
- data/lib/riffer/mcp/client.rb +0 -1
- 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/params/any_of.rb +37 -9
- data/lib/riffer/params/param.rb +35 -14
- data/lib/riffer/params.rb +34 -19
- data/lib/riffer/providers/amazon_bedrock.rb +38 -5
- data/lib/riffer/providers/anthropic/client.rb +49 -0
- data/lib/riffer/providers/anthropic.rb +19 -452
- data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +219 -0
- data/lib/riffer/providers/anthropic_compatible/messages_api.rb +315 -0
- data/lib/riffer/providers/anthropic_compatible.rb +5 -0
- data/lib/riffer/providers/anthropic_vertex.rb +66 -0
- data/lib/riffer/providers/base.rb +19 -13
- data/lib/riffer/providers/gemini/client.rb +17 -85
- data/lib/riffer/providers/gemini.rb +213 -81
- data/lib/riffer/providers/google_cloud/client.rb +106 -0
- data/lib/riffer/providers/google_cloud.rb +99 -0
- data/lib/riffer/providers/open_ai.rb +21 -16
- data/lib/riffer/providers/repository.rb +2 -0
- 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/wire/sse.rb +51 -0
- data/lib/riffer/wire.rb +31 -0
- data/lib/riffer.rb +20 -0
- data/rbs_collection.lock.yaml +24 -4
- data/sig/_private/faraday.rbs +8 -0
- data/sig/_private/googleauth.rbs +7 -0
- data/sig/generated/riffer/agent/run.rbs +5 -0
- data/sig/generated/riffer/agent/session.rbs +6 -0
- data/sig/generated/riffer/config/anthropic.rbs +6 -0
- data/sig/generated/riffer/config/future.rbs +29 -0
- data/sig/generated/riffer/config/gemini.rbs +6 -0
- data/sig/generated/riffer/config/google_cloud.rbs +28 -0
- data/sig/generated/riffer/config/pricing.rbs +0 -9
- data/sig/generated/riffer/config.rbs +10 -0
- data/sig/generated/riffer/deprecation/event.rbs +17 -0
- data/sig/generated/riffer/deprecation.rbs +27 -0
- data/sig/generated/riffer/http/client.rbs +59 -0
- data/sig/generated/riffer/http.rbs +4 -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/params/any_of.rbs +13 -5
- data/sig/generated/riffer/params/param.rbs +10 -5
- data/sig/generated/riffer/params.rbs +8 -4
- data/sig/generated/riffer/providers/amazon_bedrock.rbs +14 -2
- data/sig/generated/riffer/providers/anthropic/client.rbs +34 -0
- data/sig/generated/riffer/providers/anthropic.rbs +5 -124
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +81 -0
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +108 -0
- data/sig/generated/riffer/providers/anthropic_compatible.rbs +4 -0
- data/sig/generated/riffer/providers/anthropic_vertex.rbs +45 -0
- data/sig/generated/riffer/providers/base.rbs +5 -0
- data/sig/generated/riffer/providers/gemini/client.rbs +11 -34
- data/sig/generated/riffer/providers/gemini.rbs +66 -4
- data/sig/generated/riffer/providers/google_cloud/client.rbs +71 -0
- data/sig/generated/riffer/providers/google_cloud.rbs +64 -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/wire/sse.rbs +23 -0
- data/sig/generated/riffer/wire.rbs +17 -0
- data/sig/generated/riffer.rbs +15 -0
- data/sig/manual/riffer/deprecation.rbs +5 -0
- data/sig/manual/riffer/providers/anthropic_compatible/messages_api.rbs +8 -0
- data/sig/manual/riffer/providers/gemini.rbs +8 -0
- data/sig/manual/riffer/providers/google_cloud.rbs +8 -0
- data/sig/manual/riffer/wire.rbs +5 -0
- metadata +76 -5
- data/sig/_private/anthropic.rbs +0 -17
- data/sig/_private/riffer/providers/anthropic.rbs +0 -6
- data/sig/_private/riffer/providers/gemini.rbs +0 -7
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/.claude/rules/rbs-inline.md
CHANGED
|
@@ -40,15 +40,15 @@ attr_reader :name #: String
|
|
|
40
40
|
|
|
41
41
|
## Optional-dependency types (consumer-safe signatures)
|
|
42
42
|
|
|
43
|
-
`sig/generated/` ships with the gem and is loaded by downstream projects (`rbs collection` / `rbs -r riffer`). rbs-inline copies a method's `#:` signature **verbatim** into the shipped sig, so **never name an optional-dependency type in a `#:` signature** — `OpenAI::*`, `
|
|
43
|
+
`sig/generated/` ships with the gem and is loaded by downstream projects (`rbs collection` / `rbs -r riffer`). rbs-inline copies a method's `#:` signature **verbatim** into the shipped sig, so **never name an optional-dependency type in a `#:` signature** — `OpenAI::*`, `Aws::*`, `MCP::*`, `Async::*`, `Zeitwerk::*`, etc. A consumer who installs riffer without that gem would hit `Cannot find type`, because those providers are pluggable and the gems ship no usable RBS of their own.
|
|
44
44
|
|
|
45
45
|
**Workaround — assert the type inside the method body instead.** An inline assertion (`local = arg #: OpenAI::Models::…`) is a Steep-only hint that rbs-inline does **not** emit into the signature. Leave the SDK param/return `untyped` in the `#:` line, keep every riffer/stdlib param and return typed, and recover the SDK type with a body assertion:
|
|
46
46
|
|
|
47
47
|
```ruby
|
|
48
48
|
#: (untyped) -> String
|
|
49
49
|
def extract_content(response)
|
|
50
|
-
|
|
51
|
-
|
|
50
|
+
typed_response = response #: OpenAI::Models::Responses::Response
|
|
51
|
+
typed_response.output_text # fully type-checked against the SDK type
|
|
52
52
|
end
|
|
53
53
|
|
|
54
54
|
#: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
|
|
@@ -60,7 +60,7 @@ end
|
|
|
60
60
|
# When the return value IS the SDK object, type the return `untyped` (no body assertion needed):
|
|
61
61
|
#: (Hash[Symbol, untyped]) -> untyped
|
|
62
62
|
def execute_generate(params)
|
|
63
|
-
@client.
|
|
63
|
+
@client.responses.create(**params)
|
|
64
64
|
end
|
|
65
65
|
```
|
|
66
66
|
|
|
@@ -72,8 +72,8 @@ Dependency signatures come from [`rbs collection`](https://github.com/ruby/gem_r
|
|
|
72
72
|
|
|
73
73
|
`bin/typecheck` runs `rbs collection update` before `steep check`, keeping the lock in sync with `Gemfile.lock`; CI fails on lock drift. So after a Dependabot gem bump, run `bin/typecheck` and commit the refreshed lock. To pull newer upstream stubs, bump `revision` in `rbs_collection.yaml` and run `bin/typecheck` — pinning is what makes `update` deterministic.
|
|
74
74
|
|
|
75
|
-
- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level — full stubs for the gems upstream has nothing for (`mcp.rbs`, `zeitwerk.rbs`, `opentelemetry.rbs`, `rspec.rbs`, `aws-sdk-core/*`) plus arity patches for the provider SDKs (`openai.rbs
|
|
76
|
-
- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`)
|
|
75
|
+
- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level — full stubs for the gems upstream has nothing for (`mcp.rbs`, `zeitwerk.rbs`, `opentelemetry.rbs`, `rspec.rbs`, `aws-sdk-core/*`) plus arity patches for the provider SDKs (`openai.rbs`); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/open_ai.rbs` narrows the private `client` method to the SDK-typed client). A stub must be **deleted** once the collection covers that gem, or RBS raises `DuplicatedMethodDefinitionError`.
|
|
76
|
+
- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`), modeling an include applied dynamically (`riffer/tools/toolable.rbs`), and narrowing an inherited private `client` to a riffer-owned transport (`riffer/providers/gemini.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Annotation Conventions"). SDK-typed signatures can't ship, so they go in `_private/riffer/providers/` (a `client` narrowed to a vendor SDK client).
|
|
77
77
|
- `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`, `digest`, `ipaddr`) so `rbs -r riffer` resolves them.
|
|
78
78
|
|
|
79
79
|
## Workflow
|
data/.ruby-version
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
4.0.
|
|
1
|
+
4.0.9
|
data/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,52 @@ 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
|
+
|
|
26
|
+
## [0.55.0](https://github.com/janeapp/riffer/compare/riffer/v0.54.0...riffer/v0.55.0) (2026-10-29)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### ⚠ BREAKING CHANGES
|
|
30
|
+
|
|
31
|
+
* **gemini:** Gemini and Google Cloud structured output schemas are strict.
|
|
32
|
+
* **anthropic:** the anthropic gem is no longer used. config.anthropic.client takes a Riffer::Providers::Anthropic::Client; an Anthropic::Client raises a migration error. SDK error classes are replaced by Riffer::APIError and Faraday::Error. There are no default retries (the SDK retried twice); add them through connection:. ANTHROPIC_AUTH_TOKEN and ANTHROPIC_CUSTOM_HEADERS are no longer read. Streamed ToolCallDelta events carry the real item_id and name.
|
|
33
|
+
* **gemini:** gemini-2.x models ignore responseFormat on the Developer API and return prose, so structured output needs gemini-3 or later.
|
|
34
|
+
* **gemini:** Gemini::Client no longer accepts open_timeout, read_timeout, write_timeout, proxy_address or proxy_port; pass a connection: instead. The default read timeout is 600s (was 60s). Non-success responses raise Riffer::APIError (still a Riffer::Error), and transport failures are Faraday::Errors rather than Net::* errors. A missing API key raises Riffer::ArgumentError (an ::ArgumentError, not a Riffer::Error) instead of a 4xx Riffer::Error, and GEMINI_API_KEY is now read when config.gemini.api_key is unset.
|
|
35
|
+
|
|
36
|
+
### Features
|
|
37
|
+
|
|
38
|
+
* add Riffer::HTTP::Client Faraday transport and Riffer::APIError ([#503](https://github.com/janeapp/riffer/issues/503)) ([9ee2dfc](https://github.com/janeapp/riffer/commit/9ee2dfcd97fa74aba6ce61710f06b9df9c29f3c0))
|
|
39
|
+
* **anthropic:** replace the anthropic gem with a hand-rolled Messages API client ([#506](https://github.com/janeapp/riffer/issues/506)) ([6388c44](https://github.com/janeapp/riffer/commit/6388c446d047b4e0a0f48dfd601eaa55eb6f4fc4))
|
|
40
|
+
* **gemini:** add web search through Google Search grounding ([#510](https://github.com/janeapp/riffer/issues/510)) ([ee3c820](https://github.com/janeapp/riffer/commit/ee3c82098f514dd5b846f0cba521914a23eb7c4b))
|
|
41
|
+
* **gemini:** move Gemini::Client onto Riffer::HTTP::Client ([#505](https://github.com/janeapp/riffer/issues/505)) ([1a6798c](https://github.com/janeapp/riffer/commit/1a6798c2ed12f5486ed80b61950c6bf8d2f77905))
|
|
42
|
+
* **gemini:** send structured output as responseFormat and replay thought signatures ([#507](https://github.com/janeapp/riffer/issues/507)) ([a5299ef](https://github.com/janeapp/riffer/commit/a5299eff8166ff32b85e3d397844f08649b4dd84))
|
|
43
|
+
* **params:** add primitive variants to `Riffer::Params::AnyOf` ([#508](https://github.com/janeapp/riffer/issues/508)) ([98483b4](https://github.com/janeapp/riffer/commit/98483b4d86aa4a3c9584bc008bbe7e2f1339d48e))
|
|
44
|
+
* **providers:** add anthropic_vertex provider for Claude on Agent Platform ([#512](https://github.com/janeapp/riffer/issues/512)) ([10a55a1](https://github.com/janeapp/riffer/commit/10a55a1eecb31f59a99f44370b8e26fa45a69cd3))
|
|
45
|
+
* **providers:** add google_cloud provider for Gemini on Agent Platform ([#511](https://github.com/janeapp/riffer/issues/511)) ([b0f44d6](https://github.com/janeapp/riffer/commit/b0f44d63c8149b9d6137d446919eb09bfdef4e5a))
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
### Bug Fixes
|
|
49
|
+
|
|
50
|
+
* **amazon_bedrock:** send valid document names and "{}" for streamed calls without arguments ([#522](https://github.com/janeapp/riffer/issues/522)) ([992f678](https://github.com/janeapp/riffer/commit/992f678a5e19da1948e13d36552723e4cf097e25))
|
|
51
|
+
* **gemini:** send parallel tool results back in one turn ([#518](https://github.com/janeapp/riffer/issues/518)) ([79d11ea](https://github.com/janeapp/riffer/commit/79d11eab0dd6c503fa5482790378ca4c1f49e805))
|
|
52
|
+
* **gemini:** strict structured output schema, placeholder thought signatures, one TokenUsageDone per stream ([#520](https://github.com/janeapp/riffer/issues/520)) ([a3a1063](https://github.com/janeapp/riffer/commit/a3a1063f50ac61380d685bc75b811070f1c1147e))
|
|
53
|
+
|
|
8
54
|
## [0.54.0](https://github.com/janeapp/riffer/compare/riffer/v0.53.0...riffer/v0.54.0) (2026-10-20)
|
|
9
55
|
|
|
10
56
|
|
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.
|
|
@@ -113,6 +114,8 @@ Create a `.env` file in the project root (it is gitignored):
|
|
|
113
114
|
OPENAI_API_KEY=sk-...
|
|
114
115
|
ANTHROPIC_API_KEY=sk-ant-...
|
|
115
116
|
AWS_BEDROCK_API_TOKEN=...
|
|
117
|
+
GEMINI_API_KEY=...
|
|
118
|
+
GOOGLE_CLOUD_PROJECT=my-project
|
|
116
119
|
```
|
|
117
120
|
|
|
118
121
|
The test helper loads this file automatically via `dotenv`. Then run the specific tests that need new cassettes:
|
|
@@ -121,8 +124,30 @@ The test helper loads this file automatically via `dotenv`. Then run the specifi
|
|
|
121
124
|
bundle exec ruby -Itest test/riffer/providers/open_ai_test.rb
|
|
122
125
|
bundle exec ruby -Itest test/riffer/providers/anthropic_test.rb
|
|
123
126
|
bundle exec ruby -Itest test/riffer/providers/amazon_bedrock_test.rb
|
|
127
|
+
GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth application-default print-access-token) \
|
|
128
|
+
bundle exec ruby -Itest test/riffer/providers/anthropic_vertex_test.rb
|
|
124
129
|
```
|
|
125
130
|
|
|
131
|
+
Google Cloud tests take a short-lived access token rather than a key, so pass it on the command line instead of storing it in `.env`.
|
|
132
|
+
|
|
133
|
+
#### Acceptance tests
|
|
134
|
+
|
|
135
|
+
`test/acceptance/` runs every riffer feature against each provider it lists, one file per feature. Its cassettes live under `test/fixtures/vcr_cassettes/acceptance/` and only replay. To record, set `RIFFER_RECORD` to a VCR record mode: `once` records missing cassettes, `all` re-records every cassette the run touches. Narrow the run to one provider with `-n`:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::gemini/"
|
|
139
|
+
GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth application-default print-access-token) \
|
|
140
|
+
RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::google_cloud/"
|
|
141
|
+
eval "$(aws configure export-credentials --profile your-profile --format env)" && \
|
|
142
|
+
RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::amazon_bedrock/"
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Bedrock records with the AWS credentials in the environment when `AWS_ACCESS_KEY_ID` is set, and with `AWS_BEDROCK_API_TOKEN` otherwise. Export a profile's credentials as above instead of setting `AWS_PROFILE`, so the SDK doesn't fetch them over HTTP during a test.
|
|
146
|
+
|
|
147
|
+
A test that fails while recording leaves a partial cassette behind; delete it before recording again.
|
|
148
|
+
|
|
149
|
+
To add a provider, add its entry to `ACCEPTANCE_PROVIDERS` in `test/acceptance/acceptance_helper.rb`, including the reasoning levels its model accepts, and its model's pricing to `test/acceptance/fixtures/catalog.json`. Every feature file then runs against it. A feature the provider can't support excludes it with a reason: `acceptance_providers(except: { amazon_bedrock: "Converse has no web search tool" })`.
|
|
150
|
+
|
|
126
151
|
VCR records the HTTP interactions to `test/fixtures/vcr_cassettes/` on the first run. Subsequent runs replay from the cassettes without hitting the API. API keys are automatically filtered from recorded cassettes.
|
|
127
152
|
|
|
128
153
|
## Contributing
|
|
@@ -135,7 +160,7 @@ Please follow the [Code of Conduct](https://github.com/janeapp/riffer/blob/main/
|
|
|
135
160
|
|
|
136
161
|
## Changelog
|
|
137
162
|
|
|
138
|
-
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).
|
|
139
164
|
|
|
140
165
|
## License
|
|
141
166
|
|
data/Steepfile
CHANGED
|
@@ -4,8 +4,8 @@ D = Steep::Diagnostic
|
|
|
4
4
|
|
|
5
5
|
# RBS 4.2.0 re-validates every declaration of a module each time its type
|
|
6
6
|
# params are read, which is quadratic in how often a module is reopened. The
|
|
7
|
-
# openai
|
|
8
|
-
#
|
|
7
|
+
# openai gem reopens its namespace ~1,600 times, so loading signatures takes
|
|
8
|
+
# over a minute per Steep worker. Fixed upstream in
|
|
9
9
|
# ruby/rbs a5458a83; delete this once the bundle has an RBS release newer
|
|
10
10
|
# than 4.2.
|
|
11
11
|
if RBS::Environment::ModuleEntry.instance_method(:validate_type_params).owner == RBS::Environment::ModuleEntry
|
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
|
@@ -212,7 +212,7 @@ class SentimentAgent < Riffer::Agent
|
|
|
212
212
|
end
|
|
213
213
|
```
|
|
214
214
|
|
|
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), 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.
|
|
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.
|
|
216
216
|
|
|
217
217
|
| Strategy | Behavior |
|
|
218
218
|
| ------------------- | --------------------------------------------------------------- |
|
|
@@ -347,9 +347,28 @@ The schema sends the field as `anyOf`, with one object per variant. An answer mu
|
|
|
347
347
|
|
|
348
348
|
An optional `AnyOf` field can also be `null`.
|
|
349
349
|
|
|
350
|
+
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
|
+
|
|
352
|
+
```ruby
|
|
353
|
+
structured_output do
|
|
354
|
+
required :quantity, Riffer::Params::AnyOf, description: "A count, or a word like 'several'" do
|
|
355
|
+
variant Integer
|
|
356
|
+
variant String
|
|
357
|
+
end
|
|
358
|
+
optional :due, Riffer::Params::AnyOf do
|
|
359
|
+
variant String, format: "date"
|
|
360
|
+
variant String, enum: ["none"]
|
|
361
|
+
end
|
|
362
|
+
end
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
Each primitive variant is sent as its own `anyOf` branch. A value whose type matches no variant fails validation: `quantity must be a integer or string`. A value of the right type that fails every variant gets each variant's problems: `due must match one of the variants: variant 1 (must be a valid date), variant 2 (must be one of: none)`.
|
|
366
|
+
|
|
350
367
|
#### Limitations
|
|
351
368
|
|
|
352
|
-
|
|
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.
|
|
370
|
+
|
|
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:`.
|
|
353
372
|
|
|
354
373
|
Structured output is not compatible with streaming — calling `stream` on an agent with structured output configured raises `Riffer::ArgumentError`.
|
|
355
374
|
|
|
@@ -517,23 +536,29 @@ A tag you pass with the same key wins. The default tags count towards the provid
|
|
|
517
536
|
|
|
518
537
|
### Provider mapping
|
|
519
538
|
|
|
520
|
-
| Provider | Native request field
|
|
521
|
-
| --------------------- |
|
|
522
|
-
| Amazon Bedrock | `request_metadata` (all tags)
|
|
523
|
-
| OpenAI / Azure OpenAI | `metadata` (all tags)
|
|
524
|
-
| OpenRouter | `metadata` (all tags)
|
|
525
|
-
| Anthropic | `metadata.user_id` **only**
|
|
526
|
-
| Gemini | _(none — observability only)_
|
|
539
|
+
| Provider | Native request field | `user_id` handling |
|
|
540
|
+
| --------------------- | ------------------------------ | --------------------------------------- |
|
|
541
|
+
| Amazon Bedrock | `request_metadata` (all tags) | Ordinary entry; no dedicated user field |
|
|
542
|
+
| OpenAI / Azure OpenAI | `metadata` (all tags) | Also mapped to `safety_identifier` |
|
|
543
|
+
| OpenRouter | `metadata` (all tags) | Also mapped to `user` |
|
|
544
|
+
| Anthropic | `metadata.user_id` **only** | The only tag forwarded |
|
|
545
|
+
| Gemini | _(none — observability only)_ | Tag only; no request field |
|
|
546
|
+
| Google Cloud (Gemini) | `labels` (all tags, rewritten) | Ordinary entry; no dedicated user field |
|
|
547
|
+
| Google Cloud (Claude) | `metadata.user_id` **only** | The only tag forwarded |
|
|
527
548
|
|
|
528
|
-
If `model_options` already sets the native field (`metadata` or `
|
|
549
|
+
If `model_options` already sets the native field (`metadata`, `request_metadata` or `labels`), the tags are merged into it; a tag wins on a shared key.
|
|
529
550
|
|
|
530
551
|
**Anthropic silently drops non-`user_id` tags.** The Messages API has no free-form request-metadata field — only `metadata.user_id`. So for Anthropic, `user_id` is forwarded as `metadata: {user_id: …}` and **every other tag is dropped from the request** (it still appears on spans). This is intentional.
|
|
531
552
|
|
|
532
|
-
**Gemini is observability-only.** Riffer's Gemini adapter targets the Gemini Developer API (`generativelanguage.googleapis.com`), whose `generateContent` request has **no** `labels` field — sending unknown fields is rejected. So tags are **not** added to the Gemini request; they propagate to spans only.
|
|
553
|
+
**Gemini is observability-only.** Riffer's Gemini adapter targets the Gemini Developer API (`generativelanguage.googleapis.com`), whose `generateContent` request has **no** `labels` field — sending unknown fields is rejected. So tags are **not** added to the Gemini request; they propagate to spans only.
|
|
554
|
+
|
|
555
|
+
**Google Cloud rewrites tags into valid labels.** Agent Platform `labels` keys and values take at most 63 lowercase letters, digits, underscores and dashes, and keys start with a letter. Riffer downcases each tag, replaces any other character with `_`, cuts it to 63 characters, and drops tags whose key doesn't start with a letter. `agent: "support/triage_agent"` goes out as `agent: "support_triage_agent"`. Labels set in `model_options` are sent as is. Labels show up in Google Cloud billing reports, so high-cardinality tags such as `user_id` add one label value per user.
|
|
556
|
+
|
|
557
|
+
Claude on Google Cloud (`anthropic_vertex`) follows the Anthropic rule above.
|
|
533
558
|
|
|
534
559
|
### Provider limits (not enforced)
|
|
535
560
|
|
|
536
|
-
|
|
561
|
+
Apart from the Google Cloud rewrite above, riffer does not validate tag count, key/value length, or charset — it forwards what you give it and lets the provider reject anything out of bounds. Known limits: Bedrock `requestMetadata` ≤16 entries, key/value ≤256 chars; OpenAI / OpenRouter `metadata` ≤16 pairs (OpenRouter: 64-char keys, 512-char values).
|
|
537
562
|
|
|
538
563
|
## Expand Your Agent
|
|
539
564
|
|
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/CATALOG.md
CHANGED
|
@@ -104,14 +104,14 @@ Riffer doesn't check whether a model supports a level. If the model rejects the
|
|
|
104
104
|
|
|
105
105
|
The defaults send the level name as the provider's effort value:
|
|
106
106
|
|
|
107
|
-
| Provider
|
|
108
|
-
|
|
|
109
|
-
| OpenAI, Azure OpenAI
|
|
110
|
-
| OpenRouter
|
|
111
|
-
| Anthropic
|
|
112
|
-
| Amazon Bedrock
|
|
113
|
-
| Gemini
|
|
114
|
-
| Mock
|
|
107
|
+
| Provider | `:off` | Other levels |
|
|
108
|
+
| -------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
109
|
+
| OpenAI, Azure OpenAI | `reasoning: "none"` | `reasoning: "<level>"` |
|
|
110
|
+
| OpenRouter | `reasoning: "none"` | `reasoning: "<level>"` |
|
|
111
|
+
| Anthropic, Google Cloud (Claude) | `thinking: { type: "disabled" }` | `thinking: { type: "adaptive" }, output_config: { effort: "<level>" }` |
|
|
112
|
+
| Amazon Bedrock | `additional_model_request_fields: { thinking: { type: "disabled" } }` | `additional_model_request_fields: { thinking: { type: "adaptive" }, output_config: { effort: "<level>" } }` |
|
|
113
|
+
| Gemini, Google Cloud (Gemini) | `thinkingConfig: { thinkingLevel: "off" }` | `thinkingConfig: { thinkingLevel: "<level>" }` |
|
|
114
|
+
| Mock | nothing | nothing |
|
|
115
115
|
|
|
116
116
|
Add a catalog entry for models that need different params, for example:
|
|
117
117
|
|
data/docs/CONFIGURATION.md
CHANGED
|
@@ -18,7 +18,7 @@ end
|
|
|
18
18
|
|
|
19
19
|
Providers take no constructor arguments — these settings are the only way to give a provider its credentials.
|
|
20
20
|
|
|
21
|
-
Credential and endpoint settings — `amazon_bedrock.api_token` / `.region`, `anthropic.api_key`, `azure_openai.api_key` / `.endpoint`, `gemini.api_key`, `openai.api_key` / `.base_url`, `openrouter.api_key` — accept a `String` or `nil` and raise `Riffer::ArgumentError` naming the setting for anything else. An empty string is accepted; Amazon Bedrock treats it as unset. `client` is not validated (see [Provider Clients](#provider-clients)).
|
|
21
|
+
Credential and endpoint settings — `amazon_bedrock.api_token` / `.region`, `anthropic.api_key` / `.base_url`, `azure_openai.api_key` / `.endpoint`, `gemini.api_key` / `.base_url`, `google_cloud.project_id` / `.location`, `openai.api_key` / `.base_url`, `openrouter.api_key` — accept a `String` or `nil` and raise `Riffer::ArgumentError` naming the setting for anything else. An empty string is accepted; Amazon Bedrock treats it as unset. `client` is not validated (see [Provider Clients](#provider-clients)).
|
|
22
22
|
|
|
23
23
|
## Accessing Configuration
|
|
24
24
|
|
|
@@ -52,21 +52,22 @@ Riffer.configure do |config|
|
|
|
52
52
|
)
|
|
53
53
|
config.gemini.client = Riffer::Providers::Gemini::Client.new(
|
|
54
54
|
api_key: ENV['GEMINI_API_KEY'],
|
|
55
|
-
read_timeout: 120
|
|
55
|
+
connection: Faraday.new(request: { open_timeout: 10, read_timeout: 120 })
|
|
56
56
|
)
|
|
57
57
|
end
|
|
58
58
|
```
|
|
59
59
|
|
|
60
60
|
Every provider accepts a client instance or a `Proc` returning one:
|
|
61
61
|
|
|
62
|
-
| Provider | Setting | Default client built from credentials
|
|
63
|
-
| -------------- | ------------------------------ |
|
|
64
|
-
| OpenAI | `config.openai.client` | `OpenAI::Client`
|
|
65
|
-
| Azure OpenAI | `config.azure_openai.client` | `OpenAI::Client` (with the Azure endpoint as `base_url`)
|
|
66
|
-
| Anthropic | `config.anthropic.client` | `Anthropic::Client`
|
|
67
|
-
| Amazon Bedrock | `config.amazon_bedrock.client` | `Aws::BedrockRuntime::Client`
|
|
68
|
-
| Gemini | `config.gemini.client` | `Riffer::Providers::Gemini::Client` (riffer-owned, see below)
|
|
69
|
-
|
|
|
62
|
+
| Provider | Setting | Default client built from credentials |
|
|
63
|
+
| -------------- | ------------------------------ | ------------------------------------------------------------------ |
|
|
64
|
+
| OpenAI | `config.openai.client` | `OpenAI::Client` |
|
|
65
|
+
| Azure OpenAI | `config.azure_openai.client` | `OpenAI::Client` (with the Azure endpoint as `base_url`) |
|
|
66
|
+
| Anthropic | `config.anthropic.client` | `Riffer::Providers::Anthropic::Client` (riffer-owned) |
|
|
67
|
+
| Amazon Bedrock | `config.amazon_bedrock.client` | `Aws::BedrockRuntime::Client` |
|
|
68
|
+
| Gemini | `config.gemini.client` | `Riffer::Providers::Gemini::Client` (riffer-owned, see below) |
|
|
69
|
+
| Google Cloud | `config.google_cloud.client` | `Riffer::Providers::GoogleCloud::Client` (riffer-owned, see below) |
|
|
70
|
+
| OpenRouter | `config.openrouter.client` | `OpenAI::Client` (pinned to the OpenRouter endpoint) |
|
|
70
71
|
|
|
71
72
|
A `Proc` takes **no arguments** and is resolved on **every LLM call**, never cached by riffer — memoize inside the Proc when construction is expensive. This makes the Proc the right tool for:
|
|
72
73
|
|
|
@@ -93,11 +94,44 @@ A configured client always wins over configured credentials: once `config.<provi
|
|
|
93
94
|
|
|
94
95
|
### Falling through to the SDK
|
|
95
96
|
|
|
96
|
-
A credential you leave unset in riffer is omitted from the default client rather than passed as `nil`, so each vendor SDK still applies its own resolution. `OPENAI_API_KEY` / `OPENAI_BASE_URL
|
|
97
|
+
A credential you leave unset in riffer is omitted from the default client rather than passed as `nil`, so each vendor SDK still applies its own resolution. `OPENAI_API_KEY` / `OPENAI_BASE_URL` and the AWS chains — region from `AWS_REGION` / `AWS_DEFAULT_REGION` / shared config, credentials from the environment, the shared credentials file, or an instance/task IAM role — all work with no riffer configuration at all.
|
|
97
98
|
|
|
98
99
|
Two providers deliberately opt out: `OpenRouter` and `AzureOpenAI` borrow `OpenAI::Client` to reach a **different** vendor, so they always pass their credential and endpoint explicitly. Falling through would let the OpenAI SDK pick up `OPENAI_API_KEY` / `OPENAI_BASE_URL` and send an OpenAI credential to `openrouter.ai` or your Azure endpoint. With nothing configured they raise instead — set `config.openrouter.api_key` / `OPENROUTER_API_KEY`, or `config.azure_openai.api_key` and `.endpoint` / `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT`.
|
|
99
100
|
|
|
100
|
-
The
|
|
101
|
+
The Anthropic provider uses no vendor SDK. Riffer reads `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` itself when `config.anthropic.api_key` / `.base_url` are unset, and raises `Riffer::ArgumentError` when no key is found. Its client, `Riffer::Providers::Anthropic::Client`, takes `headers:` and a `connection:` (see [Connections](#connections) and [Anthropic](providers/ANTHROPIC.md)).
|
|
102
|
+
|
|
103
|
+
The Gemini provider has no vendor SDK, so riffer ships its own transport, `Riffer::Providers::Gemini::Client`, built on `Riffer::HTTP::Client` (see [Connections](#connections)). Its key falls back to `GEMINI_API_KEY` when `config.gemini.api_key` is unset, and raises `Riffer::ArgumentError` when neither is set. Anything implementing its two-method contract (`post`, `post_stream`) can be assigned to `config.gemini.client` — see [Gemini](providers/GEMINI.md).
|
|
104
|
+
|
|
105
|
+
The Google Cloud providers (`google_cloud` for Gemini, `anthropic_vertex` for Claude) share their own Agent Platform transport: `Riffer::Providers::GoogleCloud::Client`, also built on `Riffer::HTTP::Client`, is bound to one `project_id` and `location` and authenticates with `config.google_cloud.credentials`, or Application Default Credentials when unset. The default `"global"` location has no data-residency guarantee; see [Google Cloud → Locations and Data Residency](providers/GOOGLE_CLOUD.md#locations-and-data-residency) for pinning a location and for reaching several locations from one process.
|
|
106
|
+
|
|
107
|
+
### Connections
|
|
108
|
+
|
|
109
|
+
Clients built on `Riffer::HTTP::Client` send requests through a [Faraday](https://lostisland.github.io/faraday/) connection. The default uses Faraday's `net_http` adapter with a 10-second open timeout, a 600-second read timeout and no retries. To change any of that, pass your own connection as `connection:`. Riffer's defaults don't carry over to a connection you pass in, so set its timeouts yourself, in the form its adapter reads them. Riffer requests absolute URLs and sets the auth headers on each request, so the connection needs no `url:`.
|
|
110
|
+
|
|
111
|
+
To send extra headers, pass `headers:` to the client, or set them on the connection. Either way they go on every request and replace riffer's auth and version headers of the same name. A replaced auth header is sent as-is, never refreshed. Riffer always sets `content-type`, `accept` and `accept-encoding` itself.
|
|
112
|
+
|
|
113
|
+
For example, to retry rate limits and server errors with [faraday-retry](https://github.com/lostisland/faraday-retry):
|
|
114
|
+
|
|
115
|
+
```ruby
|
|
116
|
+
# Gemfile: gem "faraday-retry"
|
|
117
|
+
require "faraday/retry"
|
|
118
|
+
|
|
119
|
+
connection = Faraday.new(request: { open_timeout: 10, read_timeout: 300 }) do |f|
|
|
120
|
+
f.request :retry,
|
|
121
|
+
max: 2,
|
|
122
|
+
methods: [:post],
|
|
123
|
+
retry_statuses: [429, 500, 502, 503, 504, 529]
|
|
124
|
+
end
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Retrying a streaming request is only safe before any data has arrived. If a retry restarts a stream that already yielded chunks, riffer raises `Riffer::Error` rather than yield them twice.
|
|
128
|
+
|
|
129
|
+
Streaming is tested with the default `net_http` adapter.
|
|
130
|
+
|
|
131
|
+
#### Errors
|
|
132
|
+
|
|
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
|
+
- Transport failures are raised as Faraday's own errors, such as `Faraday::TimeoutError` and `Faraday::ConnectionFailed` (both `Faraday::Error`s).
|
|
101
135
|
|
|
102
136
|
### MCP (Model Context Protocol)
|
|
103
137
|
|
|
@@ -242,7 +276,7 @@ See [Model Catalog](CATALOG.md) for the file format, lookup, layering, and valid
|
|
|
242
276
|
|
|
243
277
|
### Pricing (deprecated)
|
|
244
278
|
|
|
245
|
-
`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.
|
|
246
280
|
|
|
247
281
|
```ruby
|
|
248
282
|
# before
|
|
@@ -257,6 +291,53 @@ end
|
|
|
257
291
|
|
|
258
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).
|
|
259
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
|
+
|
|
260
341
|
### Message ID Strategy
|
|
261
342
|
|
|
262
343
|
Opt in to stable identifiers on every message for logging, persistence, or replay:
|
|
@@ -348,10 +429,7 @@ end
|
|
|
348
429
|
|
|
349
430
|
| Option | Description |
|
|
350
431
|
| --------------- | ------------------------------------------- |
|
|
351
|
-
| `temperature` | Sampling temperature |
|
|
352
432
|
| `max_tokens` | Maximum tokens in response |
|
|
353
|
-
| `top_p` | Nucleus sampling parameter |
|
|
354
|
-
| `top_k` | Top-k sampling parameter |
|
|
355
433
|
| `thinking` | Extended thinking config hash (Claude 3.7+) |
|
|
356
434
|
| `output_config` | Output config hash (e.g. `effort`) |
|
|
357
435
|
| `web_search` | Enable web search (`true` or config hash) |
|
|
@@ -359,7 +437,7 @@ end
|
|
|
359
437
|
```ruby
|
|
360
438
|
class MyAgent < Riffer::Agent
|
|
361
439
|
model 'anthropic/claude-haiku-4-5-20251001'
|
|
362
|
-
model_options
|
|
440
|
+
model_options max_tokens: 4096
|
|
363
441
|
end
|
|
364
442
|
|
|
365
443
|
# With extended thinking (Claude 3.7+)
|
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
|
@@ -150,7 +150,7 @@ reg = Riffer::Mcp.registrations["github"]
|
|
|
150
150
|
reg.tools # => [<Class:...>, ...] (Riffer::Mcp::Tool subclasses; .mcp_server_tool_name returns the server-side name)
|
|
151
151
|
```
|
|
152
152
|
|
|
153
|
-
Discovery failures raise from `register` directly, typically `Faraday::Error` for network issues or `Riffer::DependencyError` if the `mcp
|
|
153
|
+
Discovery failures raise from `register` directly, typically `Faraday::Error` for network issues or `Riffer::DependencyError` if the `mcp` gem is missing. Rescue `StandardError` for graceful degradation:
|
|
154
154
|
|
|
155
155
|
```ruby
|
|
156
156
|
begin
|
|
@@ -176,11 +176,10 @@ All inherit from `Riffer::Mcp::Error < Riffer::Error`.
|
|
|
176
176
|
|
|
177
177
|
## Requirements
|
|
178
178
|
|
|
179
|
-
The `mcp`
|
|
179
|
+
The `mcp` gem is an **optional** dependency — it is not included in Riffer's runtime gemspec. To use MCP integration, add it to your own Gemfile:
|
|
180
180
|
|
|
181
181
|
```ruby
|
|
182
182
|
gem "mcp"
|
|
183
|
-
gem "faraday"
|
|
184
183
|
```
|
|
185
184
|
|
|
186
|
-
|
|
185
|
+
Its HTTP transport uses Faraday, which Riffer already depends on. If `mcp` is missing when `Riffer::Mcp.register` is called, a `Riffer::DependencyError` is raised.
|