riffer 0.53.0 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/rules/rbs-inline.md +8 -8
  3. data/.release-please-manifest.json +1 -1
  4. data/.ruby-version +1 -1
  5. data/CHANGELOG.md +43 -0
  6. data/README.md +24 -0
  7. data/Steepfile +19 -0
  8. data/docs/AGENTS.md +101 -14
  9. data/docs/CATALOG.md +8 -8
  10. data/docs/CONFIGURATION.md +47 -16
  11. data/docs/MCP.md +3 -4
  12. data/docs/OVERVIEW.md +1 -1
  13. data/docs/STREAM_EVENTS.md +1 -1
  14. data/docs/TOOLS.md +15 -12
  15. data/docs/TRACING.md +1 -1
  16. data/docs/providers/AMAZON_BEDROCK.md +2 -0
  17. data/docs/providers/ANTHROPIC.md +32 -36
  18. data/docs/providers/CUSTOM_PROVIDERS.md +35 -0
  19. data/docs/providers/GEMINI.md +76 -25
  20. data/docs/providers/GOOGLE_CLOUD.md +363 -0
  21. data/docs/providers/PROVIDERS.md +30 -18
  22. data/docs-site/manifest.yml +3 -0
  23. data/lib/riffer/agent/structured_output.rb +28 -3
  24. data/lib/riffer/config/anthropic.rb +9 -0
  25. data/lib/riffer/config/gemini.rb +9 -0
  26. data/lib/riffer/config/google_cloud.rb +38 -0
  27. data/lib/riffer/config.rb +3 -0
  28. data/lib/riffer/http/client.rb +141 -0
  29. data/lib/riffer/http.rb +5 -0
  30. data/lib/riffer/mcp/client.rb +0 -1
  31. data/lib/riffer/params/any_of.rb +50 -0
  32. data/lib/riffer/params/format.rb +73 -0
  33. data/lib/riffer/params/param.rb +143 -19
  34. data/lib/riffer/params.rb +156 -30
  35. data/lib/riffer/providers/amazon_bedrock.rb +38 -5
  36. data/lib/riffer/providers/anthropic/client.rb +49 -0
  37. data/lib/riffer/providers/anthropic.rb +19 -452
  38. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +195 -0
  39. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +293 -0
  40. data/lib/riffer/providers/anthropic_compatible.rb +5 -0
  41. data/lib/riffer/providers/anthropic_vertex.rb +66 -0
  42. data/lib/riffer/providers/base.rb +13 -16
  43. data/lib/riffer/providers/gemini/client.rb +17 -85
  44. data/lib/riffer/providers/gemini.rb +213 -80
  45. data/lib/riffer/providers/google_cloud/client.rb +106 -0
  46. data/lib/riffer/providers/google_cloud.rb +99 -0
  47. data/lib/riffer/providers/repository.rb +2 -0
  48. data/lib/riffer/version.rb +1 -1
  49. data/lib/riffer/wire/sse.rb +51 -0
  50. data/lib/riffer/wire.rb +31 -0
  51. data/lib/riffer.rb +18 -0
  52. data/rbs_collection.lock.yaml +32 -4
  53. data/rbs_collection.yaml +2 -0
  54. data/sig/_private/faraday.rbs +8 -0
  55. data/sig/_private/googleauth.rbs +7 -0
  56. data/sig/generated/riffer/agent/structured_output.rbs +6 -0
  57. data/sig/generated/riffer/config/anthropic.rbs +6 -0
  58. data/sig/generated/riffer/config/gemini.rbs +6 -0
  59. data/sig/generated/riffer/config/google_cloud.rbs +28 -0
  60. data/sig/generated/riffer/config.rbs +2 -0
  61. data/sig/generated/riffer/http/client.rbs +59 -0
  62. data/sig/generated/riffer/http.rbs +4 -0
  63. data/sig/generated/riffer/params/any_of.rbs +21 -0
  64. data/sig/generated/riffer/params/format.rbs +39 -0
  65. data/sig/generated/riffer/params/param.rbs +27 -4
  66. data/sig/generated/riffer/params.rbs +38 -8
  67. data/sig/generated/riffer/providers/amazon_bedrock.rbs +14 -2
  68. data/sig/generated/riffer/providers/anthropic/client.rbs +34 -0
  69. data/sig/generated/riffer/providers/anthropic.rbs +5 -124
  70. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +71 -0
  71. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +99 -0
  72. data/sig/generated/riffer/providers/anthropic_compatible.rbs +4 -0
  73. data/sig/generated/riffer/providers/anthropic_vertex.rbs +45 -0
  74. data/sig/generated/riffer/providers/gemini/client.rbs +11 -34
  75. data/sig/generated/riffer/providers/gemini.rbs +66 -4
  76. data/sig/generated/riffer/providers/google_cloud/client.rbs +71 -0
  77. data/sig/generated/riffer/providers/google_cloud.rbs +64 -0
  78. data/sig/generated/riffer/wire/sse.rbs +23 -0
  79. data/sig/generated/riffer/wire.rbs +17 -0
  80. data/sig/generated/riffer.rbs +12 -0
  81. data/sig/manifest.yaml +2 -1
  82. data/sig/manual/riffer/params/format.rbs +5 -0
  83. data/sig/manual/riffer/providers/anthropic_compatible/messages_api.rbs +8 -0
  84. data/sig/manual/riffer/providers/gemini.rbs +8 -0
  85. data/sig/manual/riffer/providers/google_cloud.rbs +8 -0
  86. data/sig/manual/riffer/wire.rbs +5 -0
  87. metadata +66 -5
  88. data/sig/_private/anthropic.rbs +0 -17
  89. data/sig/_private/riffer/providers/anthropic.rbs +0 -6
  90. data/sig/_private/riffer/providers/gemini.rbs +0 -7
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 70784c56c20102b8da3e1e147bc843db2287e2be910f1e10d26b8ee9a2f8e0f9
4
- data.tar.gz: 6df766acde899e39867a06de11fca0d013671e4bda34d3759b4ae310a43d04de
3
+ metadata.gz: bce35dc408dca35e5effe8987b7a8a43865720704f4c3c5f47e1c7709c733bb4
4
+ data.tar.gz: 0edac840e1a65f7cf55ef5254ed6451b2c0aba469fed02fcb62eb4891970236f
5
5
  SHA512:
6
- metadata.gz: 39af9afa9f695fe6dcc661915e1173ddf812db2ee425b83f77ee42d2080cea623b0f03f82c80ae606e7b4caf2f42bb3799a63ed0955ab7baa13b2c30861a2781
7
- data.tar.gz: 1f79ef71cf1a838092444368f6986cd772803aeffe0de9acadc5cf8c23834e0e56c04e5049001eaeab3360d13a0eb3767a8118f429cacdbad7372879706ce332
6
+ metadata.gz: b23684154e93a57612c4de3b860336804ae3ccf265a951bcc71126bcc71d8f49de1e42331418187243ce846b88c47a4dcc20d52a196680f023c5ebb9da049b9d
7
+ data.tar.gz: daaf1a51e35cd78605b82ddd11608713a0c1c2d231d8a7eae30d4048f0d60793e2c9a99aa5bbc3af6c48dd52f36ac095c860cdb7a665f39de319f6066182a1c0
@@ -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::*`, `Anthropic::*`, `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.
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
- message = response #: Anthropic::Models::Message
51
- message.content&.first&.text || "" # fully type-checked against the SDK type
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.messages.create(**params)
63
+ @client.responses.create(**params)
64
64
  end
65
65
  ```
66
66
 
@@ -68,13 +68,13 @@ end
68
68
 
69
69
  ### Where stubs and stdlib deps live
70
70
 
71
- Dependency signatures come from [`rbs collection`](https://github.com/ruby/gem_rbs_collection): `rbs_collection.yaml` pins the upstream repo to a commit SHA, the gem set is derived from `Gemfile.lock`, and `rbs_collection.lock.yaml` is committed (the installed `.gem_rbs_collection/` is gitignored). Steep auto-detects the config, so the `Steepfile` declares no `library` lines. `yaml` is the one hand-listed entry under `gems:` — it's stdlib, so it never appears in `Gemfile.lock`.
71
+ Dependency signatures come from [`rbs collection`](https://github.com/ruby/gem_rbs_collection): `rbs_collection.yaml` pins the upstream repo to a commit SHA, the gem set is derived from `Gemfile.lock`, and `rbs_collection.lock.yaml` is committed (the installed `.gem_rbs_collection/` is gitignored). Steep auto-detects the config, so the `Steepfile` declares no `library` lines. Stdlib libraries that no gem in `Gemfile.lock` pulls in are hand-listed under `gems:` (`yaml`, `cgi`, `date`, `ipaddr`).
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`, `anthropic.rbs`); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.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`) and modeling an include applied dynamically (`riffer/tools/toolable.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/` (the narrowed `client`).
77
- - `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
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
+ - `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
80
80
 
@@ -1,3 +1,3 @@
1
1
  {
2
- ".": "0.53.0"
2
+ ".": "0.55.0"
3
3
  }
data/.ruby-version CHANGED
@@ -1 +1 @@
1
- 4.0.5
1
+ 4.0.9
data/CHANGELOG.md CHANGED
@@ -5,6 +5,49 @@ 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.55.0](https://github.com/janeapp/riffer/compare/riffer/v0.54.0...riffer/v0.55.0) (2026-10-29)
9
+
10
+
11
+ ### ⚠ BREAKING CHANGES
12
+
13
+ * **gemini:** Gemini and Google Cloud structured output schemas are strict.
14
+ * **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.
15
+ * **gemini:** gemini-2.x models ignore responseFormat on the Developer API and return prose, so structured output needs gemini-3 or later.
16
+ * **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.
17
+
18
+ ### Features
19
+
20
+ * 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))
21
+ * **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))
22
+ * **gemini:** add web search through Google Search grounding ([#510](https://github.com/janeapp/riffer/issues/510)) ([ee3c820](https://github.com/janeapp/riffer/commit/ee3c82098f514dd5b846f0cba521914a23eb7c4b))
23
+ * **gemini:** move Gemini::Client onto Riffer::HTTP::Client ([#505](https://github.com/janeapp/riffer/issues/505)) ([1a6798c](https://github.com/janeapp/riffer/commit/1a6798c2ed12f5486ed80b61950c6bf8d2f77905))
24
+ * **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))
25
+ * **params:** add primitive variants to `Riffer::Params::AnyOf` ([#508](https://github.com/janeapp/riffer/issues/508)) ([98483b4](https://github.com/janeapp/riffer/commit/98483b4d86aa4a3c9584bc008bbe7e2f1339d48e))
26
+ * **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))
27
+ * **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))
28
+
29
+
30
+ ### Bug Fixes
31
+
32
+ * **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))
33
+ * **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))
34
+ * **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))
35
+
36
+ ## [0.54.0](https://github.com/janeapp/riffer/compare/riffer/v0.53.0...riffer/v0.54.0) (2026-10-20)
37
+
38
+
39
+ ### Features
40
+
41
+ * **params:** add `format:` for string formats ([#497](https://github.com/janeapp/riffer/issues/497)) ([3c2dec8](https://github.com/janeapp/riffer/commit/3c2dec8e70b28de2d7b9d655e8d17ce85dde6812))
42
+ * **params:** add `Riffer::Params::AnyOf` ([#491](https://github.com/janeapp/riffer/issues/491)) ([65493ca](https://github.com/janeapp/riffer/commit/65493caa8073cf86983ec27dc6fb84ede068b6b9))
43
+ * **params:** add arrays of arrays with nested `of:` ([#498](https://github.com/janeapp/riffer/issues/498)) ([2b3449c](https://github.com/janeapp/riffer/commit/2b3449c61474f5cc79643903c08668a8fd9db8b6))
44
+ * **structured_output:** append prompted schema to user messages ([#492](https://github.com/janeapp/riffer/issues/492)) ([332db21](https://github.com/janeapp/riffer/commit/332db216d2e7716904d5ff4a9c1d9d42e128ac83))
45
+
46
+
47
+ ### Bug Fixes
48
+
49
+ * **params:** apply enum to each item of an Array of: param ([#493](https://github.com/janeapp/riffer/issues/493)) ([09da9b0](https://github.com/janeapp/riffer/commit/09da9b0ccb0e63b2ed3202a28546371b17118e8c))
50
+
8
51
  ## [0.53.0](https://github.com/janeapp/riffer/compare/riffer/v0.52.1...riffer/v0.53.0) (2026-10-13)
9
52
 
10
53
 
data/README.md CHANGED
@@ -113,6 +113,8 @@ Create a `.env` file in the project root (it is gitignored):
113
113
  OPENAI_API_KEY=sk-...
114
114
  ANTHROPIC_API_KEY=sk-ant-...
115
115
  AWS_BEDROCK_API_TOKEN=...
116
+ GEMINI_API_KEY=...
117
+ GOOGLE_CLOUD_PROJECT=my-project
116
118
  ```
117
119
 
118
120
  The test helper loads this file automatically via `dotenv`. Then run the specific tests that need new cassettes:
@@ -121,8 +123,30 @@ The test helper loads this file automatically via `dotenv`. Then run the specifi
121
123
  bundle exec ruby -Itest test/riffer/providers/open_ai_test.rb
122
124
  bundle exec ruby -Itest test/riffer/providers/anthropic_test.rb
123
125
  bundle exec ruby -Itest test/riffer/providers/amazon_bedrock_test.rb
126
+ GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth application-default print-access-token) \
127
+ bundle exec ruby -Itest test/riffer/providers/anthropic_vertex_test.rb
124
128
  ```
125
129
 
130
+ 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`.
131
+
132
+ #### Acceptance tests
133
+
134
+ `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`:
135
+
136
+ ```bash
137
+ RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::gemini/"
138
+ GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth application-default print-access-token) \
139
+ RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::google_cloud/"
140
+ eval "$(aws configure export-credentials --profile your-profile --format env)" && \
141
+ RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::amazon_bedrock/"
142
+ ```
143
+
144
+ 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.
145
+
146
+ A test that fails while recording leaves a partial cassette behind; delete it before recording again.
147
+
148
+ 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" })`.
149
+
126
150
  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
151
 
128
152
  ## Contributing
data/Steepfile CHANGED
@@ -2,6 +2,25 @@
2
2
 
3
3
  D = Steep::Diagnostic
4
4
 
5
+ # RBS 4.2.0 re-validates every declaration of a module each time its type
6
+ # params are read, which is quadratic in how often a module is reopened. The
7
+ # openai gem reopens its namespace ~1,600 times, so loading signatures takes
8
+ # over a minute per Steep worker. Fixed upstream in
9
+ # ruby/rbs a5458a83; delete this once the bundle has an RBS release newer
10
+ # than 4.2.
11
+ if RBS::Environment::ModuleEntry.instance_method(:validate_type_params).owner == RBS::Environment::ModuleEntry
12
+ validate_once = Module.new do
13
+ def validate_type_params
14
+ return if @validated_decl_count == context_decls.size
15
+
16
+ super
17
+ @validated_decl_count = context_decls.size
18
+ end
19
+ end
20
+ RBS::Environment::ModuleEntry.prepend(validate_once)
21
+ RBS::Environment::ClassEntry.prepend(validate_once)
22
+ end
23
+
5
24
  target :lib do
6
25
  signature "sig/generated"
7
26
  signature "sig/manual"
data/docs/AGENTS.md CHANGED
@@ -212,12 +212,12 @@ 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 carrying the JSON Schema is appended to the system instructions on every request of the run (it is not stored in `session.messages`), and 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
  | ------------------- | --------------------------------------------------------------- |
219
219
  | `:native` (default) | Schema sent through the provider's structured-output field |
220
- | `:prompted` | Schema sent in the system prompt; experimental, may change |
220
+ | `:prompted` | Schema appended to each user message; experimental, may change |
221
221
 
222
222
  Riffer does not pick a strategy per model — 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 `Riffer::Params` instance: `structured_output params, strategy: :prompted`.
223
223
 
@@ -249,7 +249,46 @@ structured_output do
249
249
  end
250
250
  ```
251
251
 
252
- Only primitive types are allowed with `of:`: `String`, `Integer`, `Float`, `TrueClass`, `FalseClass`.
252
+ `of:` takes a primitive type: `String`, `Integer`, `Float`, `Riffer::Params::Boolean`, `TrueClass`, `FalseClass`.
253
+
254
+ Add `enum:` to limit each item to a list of values:
255
+
256
+ ```ruby
257
+ structured_output do
258
+ required :tags, Array, of: String, enum: %w[urgent billing technical]
259
+ end
260
+ ```
261
+
262
+ An item outside the list fails validation with its index: `tags[1] must be one of: urgent, billing, technical`.
263
+
264
+ For an array of arrays, put the type in brackets. Each pair of brackets adds a level, and `enum:` and `format:` apply to the innermost items:
265
+
266
+ ```ruby
267
+ structured_output do
268
+ required :rows, Array, of: [Integer], description: "Seat numbers, one array per row"
269
+ required :board, Array, of: [String], enum: %w[x o]
270
+ end
271
+ ```
272
+
273
+ A row that isn't an array fails validation with its index: `rows[1] must be an array`.
274
+
275
+ #### Formats
276
+
277
+ Use `format:` on a `String`, or on an `Array` whose innermost type is `String`, to require a standard string format:
278
+
279
+ ```ruby
280
+ structured_output do
281
+ required :born_on, String, format: "date"
282
+ optional :email, String, format: "email"
283
+ required :visit_ids, Array, of: String, format: "uuid"
284
+ end
285
+ ```
286
+
287
+ Supported formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid`. Dates and times use RFC 3339 syntax, and a `time` may leave out its UTC offset. `email` and `hostname` are checked loosely, rejecting only values that are clearly not an address or a host name.
288
+
289
+ A value that doesn't match fails validation, with its index on an array: `born_on must be a valid date`, `visit_ids[1] must be a valid uuid`. Values stay strings.
290
+
291
+ A model that must match a format writes a matching value even when it has none, so it may invent an email. Make such a field `optional` so the model can return `null`.
253
292
 
254
293
  #### Arrays of Objects
255
294
 
@@ -285,9 +324,51 @@ structured_output do
285
324
  end
286
325
  ```
287
326
 
327
+ #### Either/Or Shapes
328
+
329
+ Use `Riffer::Params::AnyOf` when a field must be one of several object shapes. Each `variant` block defines one shape, the same way a `Hash` block does:
330
+
331
+ ```ruby
332
+ structured_output do
333
+ required :result, Riffer::Params::AnyOf, description: "The address, or why none was found" do
334
+ variant do
335
+ required :street, String, description: "Street address"
336
+ required :city, String, description: "City"
337
+ end
338
+ variant do
339
+ required :error_code, String, enum: %w[no_address multiple_addresses]
340
+ required :error_message, String
341
+ end
342
+ end
343
+ end
344
+ ```
345
+
346
+ 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
+
348
+ An optional `AnyOf` field can also be `null`.
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
+
288
367
  #### Limitations
289
368
 
290
- 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`) also raises `Riffer::ArgumentError`.
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:`.
291
372
 
292
373
  Structured output is not compatible with streaming — calling `stream` on an agent with structured output configured raises `Riffer::ArgumentError`.
293
374
 
@@ -455,23 +536,29 @@ A tag you pass with the same key wins. The default tags count towards the provid
455
536
 
456
537
  ### Provider mapping
457
538
 
458
- | Provider | Native request field | `user_id` handling |
459
- | --------------------- | ----------------------------- | --------------------------------------- |
460
- | Amazon Bedrock | `request_metadata` (all tags) | Ordinary entry; no dedicated user field |
461
- | OpenAI / Azure OpenAI | `metadata` (all tags) | Also mapped to `safety_identifier` |
462
- | OpenRouter | `metadata` (all tags) | Also mapped to `user` |
463
- | Anthropic | `metadata.user_id` **only** | The only tag forwarded |
464
- | Gemini | _(none — observability only)_ | Tag only; no request field |
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 |
465
548
 
466
- If `model_options` already sets the native field (`metadata` or `request_metadata`), the tags are merged into it; a tag wins on a shared key.
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.
467
550
 
468
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.
469
552
 
470
- **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. Native request labels (`labels`, lowercase `[a-z0-9_-]`, ≤63 chars each) are a Vertex AI feature and would arrive with a future Vertex adapter.
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.
471
558
 
472
559
  ### Provider limits (not enforced)
473
560
 
474
- 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).
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).
475
562
 
476
563
  ## Expand Your Agent
477
564
 
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 | `:off` | Other levels |
108
- | -------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
109
- | OpenAI, Azure OpenAI | `reasoning: "none"` | `reasoning: "<level>"` |
110
- | OpenRouter | `reasoning: "none"` | `reasoning: "<level>"` |
111
- | Anthropic | `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 | `thinkingConfig: { thinkingLevel: "off" }` | `thinkingConfig: { thinkingLevel: "<level>" }` |
114
- | Mock | nothing | nothing |
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
 
@@ -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
- | OpenRouter | `config.openrouter.client` | `OpenAI::Client` (pinned to the OpenRouter endpoint) |
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`, `ANTHROPIC_API_KEY`, 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
+ 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 Gemini provider has no vendor SDK, so riffer ships its own transport: `Riffer::Providers::Gemini::Client` exposes `base_url`, `open_timeout`, `read_timeout`, `write_timeout`, and `proxy_address`/`proxy_port`. Anything implementing its two-method contract (`post`, `post_stream`) can be assigned to `config.gemini.client` — see [Gemini](providers/GEMINI.md).
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
 
@@ -348,10 +382,7 @@ end
348
382
 
349
383
  | Option | Description |
350
384
  | --------------- | ------------------------------------------- |
351
- | `temperature` | Sampling temperature |
352
385
  | `max_tokens` | Maximum tokens in response |
353
- | `top_p` | Nucleus sampling parameter |
354
- | `top_k` | Top-k sampling parameter |
355
386
  | `thinking` | Extended thinking config hash (Claude 3.7+) |
356
387
  | `output_config` | Output config hash (e.g. `effort`) |
357
388
  | `web_search` | Enable web search (`true` or config hash) |
@@ -359,7 +390,7 @@ end
359
390
  ```ruby
360
391
  class MyAgent < Riffer::Agent
361
392
  model 'anthropic/claude-haiku-4-5-20251001'
362
- model_options temperature: 0.7, max_tokens: 4096
393
+ model_options max_tokens: 4096
363
394
  end
364
395
 
365
396
  # With extended thinking (Claude 3.7+)
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`/`faraday` gems are missing. Rescue `StandardError` for graceful degradation:
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` and `faraday` gems are **optional** dependencies — they are not included in Riffer's runtime gemspec. To use MCP integration, add both to your own Gemfile:
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
- Faraday is required for the MCP HTTP transport. If either gem is missing when `Riffer::Mcp.register` is called, a `Riffer::DependencyError` is raised.
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.
data/docs/OVERVIEW.md CHANGED
@@ -39,7 +39,7 @@ See [Tools](TOOLS.md) for details.
39
39
 
40
40
  ### Structured Output
41
41
 
42
- Agents can return structured JSON responses that conform to a schema. The response is automatically parsed and validated. Schemas support nested objects (`Hash`), typed arrays (`Array, of:`), and arrays of objects (`Array` with block):
42
+ Agents can return structured JSON responses that conform to a schema. The response is automatically parsed and validated. Schemas support nested objects (`Hash`), typed arrays (`Array, of:`), arrays of arrays (`Array, of: [Integer]`), arrays of objects (`Array` with block), and either/or shapes (`Riffer::Params::AnyOf`):
43
43
 
44
44
  ```ruby
45
45
  class SentimentAgent < Riffer::Agent
@@ -310,7 +310,7 @@ When an agent uses tools during streaming, the flow is:
310
310
  5. More text events stream in
311
311
  6. Repeat until no more tool calls
312
312
 
313
- > **Note:** When `web_search` is enabled, `WebSearchStatus` and `WebSearchDone` events may appear before text events as the provider performs a server-side search.
313
+ > **Note:** When `web_search` is enabled, `WebSearchStatus` and `WebSearchDone` events may appear before text events as the provider performs a server-side search. Gemini sends its `WebSearchDone` after the text.
314
314
 
315
315
  ```ruby
316
316
  agent.stream("What's the weather in Tokyo?").each do |event|
data/docs/TOOLS.md CHANGED
@@ -82,7 +82,8 @@ end
82
82
  Options:
83
83
 
84
84
  - `description` - Human-readable description for the LLM
85
- - `enum` - Array of allowed values
85
+ - `enum` - Array of allowed values (for the innermost items of an `Array` with `of:`)
86
+ - `format` - String format such as `"date"` or `"email"` (for the innermost `String` items of an `Array`; see [Formats](AGENTS.md#formats))
86
87
 
87
88
  ### optional
88
89
 
@@ -99,19 +100,21 @@ Options:
99
100
 
100
101
  - `description` - Human-readable description
101
102
  - `default` - Default value when not provided
102
- - `enum` - Array of allowed values
103
+ - `enum` - Array of allowed values (for the innermost items of an `Array` with `of:`)
104
+ - `format` - String format such as `"date"` or `"email"` (for the innermost `String` items of an `Array`; see [Formats](AGENTS.md#formats))
103
105
 
104
106
  ### Supported Types
105
107
 
106
- | Ruby Type | JSON Schema Type |
107
- | -------------------------- | ---------------- |
108
- | `String` | `string` |
109
- | `Integer` | `integer` |
110
- | `Float` | `number` |
111
- | `Riffer::Params::Boolean` | `boolean` |
112
- | `TrueClass` / `FalseClass` | `boolean` |
113
- | `Array` | `array` |
114
- | `Hash` | `object` |
108
+ | Ruby Type | JSON Schema Type |
109
+ | -------------------------- | -------------------------------- |
110
+ | `String` | `string` |
111
+ | `Integer` | `integer` |
112
+ | `Float` | `number` |
113
+ | `Riffer::Params::Boolean` | `boolean` |
114
+ | `TrueClass` / `FalseClass` | `boolean` |
115
+ | `Array` | `array` |
116
+ | `Hash` | `object` |
117
+ | `Riffer::Params::AnyOf` | `anyOf` of objects or primitives |
115
118
 
116
119
  `Riffer::Params::Boolean` is the preferred way to declare boolean parameters. `TrueClass` and `FalseClass` continue to work for backwards compatibility.
117
120
 
@@ -119,7 +122,7 @@ A `Float` param accepts a whole number too, since JSON Schema's `number` covers
119
122
 
120
123
  ### Nested Parameters
121
124
 
122
- Tool params support the same nested DSL as structured output — nested objects (`Hash` with block), typed arrays (`Array, of:`), and arrays of objects (`Array` with block). See the [structured output section in Agents](AGENTS.md#nested-objects) for full syntax.
125
+ Tool params support the same nested DSL as structured output — nested objects (`Hash` with block), typed arrays (`Array, of:`), arrays of arrays (`Array, of: [Integer]`), arrays of objects (`Array` with block), and either/or shapes (`Riffer::Params::AnyOf` with `variant`s). See the [structured output section in Agents](AGENTS.md#nested-objects) for full syntax.
123
126
 
124
127
  ```ruby
125
128
  class CreateOrderTool < Riffer::Tool
data/docs/TRACING.md CHANGED
@@ -267,7 +267,7 @@ When enabled, content is serialized as GenAI-semconv JSON strings. File attachme
267
267
 
268
268
  ## Provider names
269
269
 
270
- `gen_ai.provider.name` carries a GenAI-semconv well-known value where one exists: `openai`, `anthropic`, `aws.bedrock`, `azure.ai.openai`, `gcp.gemini`, `openrouter`. A custom provider that doesn't override the value defaults to the snake_cased form of its class name, so enabling tracing never breaks an otherwise-working provider.
270
+ `gen_ai.provider.name` carries a GenAI-semconv well-known value where one exists: `openai`, `anthropic`, `aws.bedrock`, `azure.ai.openai`, `gcp.gemini`, `gcp.vertex_ai`, `openrouter`. A custom provider that doesn't override the value defaults to the snake_cased form of its class name, so enabling tracing never breaks an otherwise-working provider.
271
271
 
272
272
  ## Stability
273
273
 
@@ -212,6 +212,8 @@ response = provider.generate_text(
212
212
  )
213
213
  ```
214
214
 
215
+ Converse requires every document to have a name, unique across the request, made only of letters, digits, single spaces, hyphens, parentheses and square brackets, and at most 200 characters long. Riffer builds it from the file's `filename`: the extension is dropped, other characters become hyphens, the name is cut to 200 characters, a document without a filename is named `document`, and a repeated name gets a counter (`invoice`, `invoice (2)`). The model can see the name.
216
+
215
217
  Any other URL scheme (e.g. `https://`) isn't something Bedrock accepts as a reference, so riffer downloads the file itself and sends the raw bytes — see [File Downloads](../CONFIGURATION.md#file-downloads) for the `allow_downloads` policy this requires.
216
218
 
217
219
  **A `sha256:` on an `s3://` `FilePart` is a combination that always fails with the default setup.** Setting `sha256:` forces riffer to download and verify the file itself before Bedrock ever sees it, regardless of the URL scheme — but riffer's default downloader only fetches `https://` URLs, so an `s3://` source can never be verified out of the box. Either configure a custom `Riffer.config.files.downloader` that can reach S3, or omit `sha256:` and let the `s3://` URI pass straight through to Bedrock unverified.