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.
Files changed (117) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/rules/rbs-inline.md +6 -6
  3. data/.release-please-manifest.json +1 -1
  4. data/.ruby-version +1 -1
  5. data/CHANGELOG.md +46 -0
  6. data/README.md +26 -1
  7. data/Steepfile +2 -2
  8. data/UPGRADING.md +3 -0
  9. data/docs/AGENTS.md +37 -12
  10. data/docs/AGENT_LIFECYCLE.md +1 -1
  11. data/docs/CATALOG.md +8 -8
  12. data/docs/CONFIGURATION.md +95 -17
  13. data/docs/GUARDRAILS.md +2 -0
  14. data/docs/MCP.md +3 -4
  15. data/docs/MESSAGES.md +112 -15
  16. data/docs/STABILITY.md +32 -0
  17. data/docs/STREAM_EVENTS.md +17 -1
  18. data/docs/TESTING.md +22 -1
  19. data/docs/TOOLS.md +11 -11
  20. data/docs/TRACING.md +1 -1
  21. data/docs/providers/AMAZON_BEDROCK.md +3 -1
  22. data/docs/providers/ANTHROPIC.md +44 -44
  23. data/docs/providers/CUSTOM_PROVIDERS.md +59 -0
  24. data/docs/providers/GEMINI.md +76 -26
  25. data/docs/providers/GOOGLE_CLOUD.md +363 -0
  26. data/docs/providers/MOCK_PROVIDER.md +2 -0
  27. data/docs/providers/OPENAI.md +3 -1
  28. data/docs/providers/PROVIDERS.md +30 -18
  29. data/docs-site/manifest.yml +6 -0
  30. data/lib/riffer/agent/run.rb +28 -13
  31. data/lib/riffer/agent/session.rb +33 -10
  32. data/lib/riffer/agent/structured_output.rb +6 -1
  33. data/lib/riffer/config/anthropic.rb +9 -0
  34. data/lib/riffer/config/future.rb +53 -0
  35. data/lib/riffer/config/gemini.rb +9 -0
  36. data/lib/riffer/config/google_cloud.rb +38 -0
  37. data/lib/riffer/config/pricing.rb +5 -15
  38. data/lib/riffer/config.rb +19 -0
  39. data/lib/riffer/deprecation/event.rb +25 -0
  40. data/lib/riffer/deprecation.rb +60 -0
  41. data/lib/riffer/http/client.rb +141 -0
  42. data/lib/riffer/http.rb +5 -0
  43. data/lib/riffer/mcp/client.rb +0 -1
  44. data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
  45. data/lib/riffer/messages/assistant/text_part.rb +52 -0
  46. data/lib/riffer/messages/assistant.rb +64 -17
  47. data/lib/riffer/params/any_of.rb +37 -9
  48. data/lib/riffer/params/param.rb +35 -14
  49. data/lib/riffer/params.rb +34 -19
  50. data/lib/riffer/providers/amazon_bedrock.rb +38 -5
  51. data/lib/riffer/providers/anthropic/client.rb +49 -0
  52. data/lib/riffer/providers/anthropic.rb +19 -452
  53. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +219 -0
  54. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +315 -0
  55. data/lib/riffer/providers/anthropic_compatible.rb +5 -0
  56. data/lib/riffer/providers/anthropic_vertex.rb +66 -0
  57. data/lib/riffer/providers/base.rb +19 -13
  58. data/lib/riffer/providers/gemini/client.rb +17 -85
  59. data/lib/riffer/providers/gemini.rb +213 -81
  60. data/lib/riffer/providers/google_cloud/client.rb +106 -0
  61. data/lib/riffer/providers/google_cloud.rb +99 -0
  62. data/lib/riffer/providers/open_ai.rb +21 -16
  63. data/lib/riffer/providers/repository.rb +2 -0
  64. data/lib/riffer/stream_events/server_tool_done.rb +21 -0
  65. data/lib/riffer/testing.rb +6 -0
  66. data/lib/riffer/version.rb +1 -1
  67. data/lib/riffer/wire/sse.rb +51 -0
  68. data/lib/riffer/wire.rb +31 -0
  69. data/lib/riffer.rb +20 -0
  70. data/rbs_collection.lock.yaml +24 -4
  71. data/sig/_private/faraday.rbs +8 -0
  72. data/sig/_private/googleauth.rbs +7 -0
  73. data/sig/generated/riffer/agent/run.rbs +5 -0
  74. data/sig/generated/riffer/agent/session.rbs +6 -0
  75. data/sig/generated/riffer/config/anthropic.rbs +6 -0
  76. data/sig/generated/riffer/config/future.rbs +29 -0
  77. data/sig/generated/riffer/config/gemini.rbs +6 -0
  78. data/sig/generated/riffer/config/google_cloud.rbs +28 -0
  79. data/sig/generated/riffer/config/pricing.rbs +0 -9
  80. data/sig/generated/riffer/config.rbs +10 -0
  81. data/sig/generated/riffer/deprecation/event.rbs +17 -0
  82. data/sig/generated/riffer/deprecation.rbs +27 -0
  83. data/sig/generated/riffer/http/client.rbs +59 -0
  84. data/sig/generated/riffer/http.rbs +4 -0
  85. data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
  86. data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
  87. data/sig/generated/riffer/messages/assistant.rbs +24 -11
  88. data/sig/generated/riffer/params/any_of.rbs +13 -5
  89. data/sig/generated/riffer/params/param.rbs +10 -5
  90. data/sig/generated/riffer/params.rbs +8 -4
  91. data/sig/generated/riffer/providers/amazon_bedrock.rbs +14 -2
  92. data/sig/generated/riffer/providers/anthropic/client.rbs +34 -0
  93. data/sig/generated/riffer/providers/anthropic.rbs +5 -124
  94. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +81 -0
  95. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +108 -0
  96. data/sig/generated/riffer/providers/anthropic_compatible.rbs +4 -0
  97. data/sig/generated/riffer/providers/anthropic_vertex.rbs +45 -0
  98. data/sig/generated/riffer/providers/base.rbs +5 -0
  99. data/sig/generated/riffer/providers/gemini/client.rbs +11 -34
  100. data/sig/generated/riffer/providers/gemini.rbs +66 -4
  101. data/sig/generated/riffer/providers/google_cloud/client.rbs +71 -0
  102. data/sig/generated/riffer/providers/google_cloud.rbs +64 -0
  103. data/sig/generated/riffer/providers/open_ai.rbs +7 -2
  104. data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
  105. data/sig/generated/riffer/testing.rbs +4 -0
  106. data/sig/generated/riffer/wire/sse.rbs +23 -0
  107. data/sig/generated/riffer/wire.rbs +17 -0
  108. data/sig/generated/riffer.rbs +15 -0
  109. data/sig/manual/riffer/deprecation.rbs +5 -0
  110. data/sig/manual/riffer/providers/anthropic_compatible/messages_api.rbs +8 -0
  111. data/sig/manual/riffer/providers/gemini.rbs +8 -0
  112. data/sig/manual/riffer/providers/google_cloud.rbs +8 -0
  113. data/sig/manual/riffer/wire.rbs +5 -0
  114. metadata +76 -5
  115. data/sig/_private/anthropic.rbs +0 -17
  116. data/sig/_private/riffer/providers/anthropic.rbs +0 -6
  117. data/sig/_private/riffer/providers/gemini.rbs +0 -7
@@ -69,6 +69,9 @@ groups:
69
69
  - source: TRACING.md
70
70
  slug: tracing
71
71
  description: OpenTelemetry spans
72
+ - source: STABILITY.md
73
+ slug: stability
74
+ description: What's safe to depend on and how upgrades work
72
75
 
73
76
  - label: Providers
74
77
  tone: jane
@@ -91,6 +94,9 @@ groups:
91
94
  - source: providers/GEMINI.md
92
95
  slug: providers/gemini
93
96
  description: Google Gemini models
97
+ - source: providers/GOOGLE_CLOUD.md
98
+ slug: providers/google-cloud
99
+ description: Gemini and Claude on Agent Platform
94
100
  - source: providers/OPENROUTER.md
95
101
  slug: providers/openrouter
96
102
  description: Hundreds of models, one API
@@ -129,9 +129,9 @@ module Riffer::Agent::Run
129
129
  #--
130
130
  #: (Riffer::Agent, Enumerator::Yielder, ?Hash[String, String]) -> Riffer::Messages::Assistant
131
131
  def accumulate_streamed_response(agent, stream_yielder, tags = {})
132
- accumulated_content = +""
133
- accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
134
- accumulated_reasoning = [] #: Array[Riffer::Messages::Assistant::ReasoningPart]
132
+ # Text deltas between two non-text events form one text part.
133
+ parts = [] #: Array[String | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
134
+ final_text = nil #: String?
135
135
  accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
136
136
  accumulated_finish_reason = nil #: Symbol?
137
137
  accumulated_finish_reason_raw = nil #: String?
@@ -141,21 +141,20 @@ module Riffer::Agent::Run
141
141
 
142
142
  case event
143
143
  when Riffer::StreamEvents::TextDelta
144
+ last = parts.last
144
145
  # << rather than +=, which copies the whole buffer per delta (O(n^2)
145
146
  # over a stream).
146
- accumulated_content << event.content
147
+ last.is_a?(String) ? last << event.content : parts << event.content.dup
147
148
  when Riffer::StreamEvents::TextDone
148
- # replace, not =, so a later delta's << can never mutate the string
149
- # this event holds.
150
- accumulated_content.replace(event.content)
149
+ final_text = event.content
151
150
  when Riffer::StreamEvents::ToolCallDone
152
- accumulated_tool_calls << Riffer::Messages::Assistant::ToolCall.new(
151
+ parts << Riffer::Messages::Assistant::ToolCall.new(
153
152
  call_id: event.call_id,
154
153
  name: event.name,
155
154
  arguments: event.arguments,
156
155
  )
157
- when Riffer::StreamEvents::ReasoningDone
158
- accumulated_reasoning << event.part
156
+ when Riffer::StreamEvents::ReasoningDone, Riffer::StreamEvents::ServerToolDone
157
+ parts << event.part
159
158
  when Riffer::StreamEvents::TokenUsageDone
160
159
  accumulated_token_usage = event.token_usage
161
160
  when Riffer::StreamEvents::FinishReasonDone
@@ -165,15 +164,31 @@ module Riffer::Agent::Run
165
164
  end
166
165
 
167
166
  Riffer::Messages::Assistant.new(
168
- accumulated_content,
169
- tool_calls: accumulated_tool_calls,
170
- reasoning: accumulated_reasoning,
167
+ parts: streamed_parts(parts, final_text),
171
168
  token_usage: accumulated_token_usage,
172
169
  finish_reason: accumulated_finish_reason,
173
170
  finish_reason_raw: accumulated_finish_reason_raw,
174
171
  )
175
172
  end
176
173
 
174
+ # TextDone is the adapter's authoritative full text, so it wins over the deltas.
175
+ #--
176
+ #: (Array[String | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart], String?) -> Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
177
+ def streamed_parts(parts, final_text)
178
+ streamed_text = parts.grep(String).join
179
+ if final_text && final_text != streamed_text
180
+ index = parts.index { |part| part.is_a?(String) } || parts.length
181
+ parts = parts.grep_v(String)
182
+ parts.insert(index, final_text)
183
+ end
184
+
185
+ parts.filter_map do |part|
186
+ next part unless part.is_a?(String)
187
+
188
+ Riffer::Messages::Assistant::TextPart.new(part) unless part.empty?
189
+ end
190
+ end
191
+
177
192
  #--
178
193
  #: (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
179
194
  def record_modifications!(stream_yielder, all_modifications, new_modifications)
@@ -191,16 +191,7 @@ class Riffer::Agent::Session
191
191
  def rebuild_message(old, attrs)
192
192
  case old
193
193
  when Riffer::Messages::Assistant
194
- Riffer::Messages::Assistant.new(
195
- attrs.fetch(:content, old.content),
196
- id: attrs.fetch(:id, old.id),
197
- tool_calls: attrs.fetch(:tool_calls, old.tool_calls),
198
- reasoning: attrs.fetch(:reasoning, old.reasoning),
199
- token_usage: attrs.fetch(:token_usage, old.token_usage),
200
- structured_output: attrs.fetch(:structured_output, old.structured_output),
201
- finish_reason: attrs.fetch(:finish_reason, old.finish_reason),
202
- finish_reason_raw: attrs.fetch(:finish_reason_raw, old.finish_reason_raw),
203
- )
194
+ rebuild_assistant(old, attrs)
204
195
  when Riffer::Messages::Tool
205
196
  Riffer::Messages::Tool.new(
206
197
  attrs.fetch(:content, old.content),
@@ -223,4 +214,36 @@ class Riffer::Agent::Session
223
214
  )
224
215
  end
225
216
  end
217
+
218
+ # A +content+, +tool_calls+ or +reasoning+ edit rebuilds the parts in the default order, which
219
+ # drops server tool parts; +parts:+ replaces them as given.
220
+ #--
221
+ #: (Riffer::Messages::Assistant, Hash[Symbol, untyped]) -> Riffer::Messages::Assistant
222
+ def rebuild_assistant(old, attrs)
223
+ options = {
224
+ id: attrs.fetch(:id, old.id),
225
+ token_usage: attrs.fetch(:token_usage, old.token_usage),
226
+ structured_output: attrs.fetch(:structured_output, old.structured_output),
227
+ finish_reason: attrs.fetch(:finish_reason, old.finish_reason),
228
+ finish_reason_raw: attrs.fetch(:finish_reason_raw, old.finish_reason_raw),
229
+ } #: Hash[Symbol, untyped]
230
+ field_edit = attrs.key?(:content) || attrs.key?(:tool_calls) || attrs.key?(:reasoning)
231
+
232
+ if attrs.key?(:parts) || !field_edit
233
+ return Riffer::Messages::Assistant.new(
234
+ attrs[:content],
235
+ parts: attrs.fetch(:parts, old.parts),
236
+ tool_calls: attrs.fetch(:tool_calls, []),
237
+ reasoning: attrs.fetch(:reasoning, []),
238
+ **options,
239
+ )
240
+ end
241
+
242
+ Riffer::Messages::Assistant.new(
243
+ attrs.fetch(:content, old.content),
244
+ tool_calls: attrs.fetch(:tool_calls, old.tool_calls),
245
+ reasoning: attrs.fetch(:reasoning, old.reasoning),
246
+ **options,
247
+ )
248
+ end
226
249
  end
@@ -58,7 +58,12 @@ class Riffer::Agent::StructuredOutput
58
58
  #: (Hash[Symbol, untyped]) -> untyped
59
59
  def placeholder(schema)
60
60
  return schema[:enum].join(" | ") if schema[:enum]
61
- return placeholder(schema[:anyOf].first) if schema[:anyOf]
61
+
62
+ if schema[:anyOf]
63
+ examples = schema[:anyOf].map { |branch| placeholder(branch) }
64
+ # Showing one primitive branch would steer the model to that type only.
65
+ return examples.all?(String) ? examples.join(" | ") : examples.first
66
+ end
62
67
 
63
68
  case schema[:type]
64
69
  when "object" then (schema[:properties] || {}).transform_values { |property| placeholder(property) }
@@ -4,12 +4,15 @@
4
4
  class Riffer::Config::Anthropic
5
5
  attr_reader :api_key #: String? # @dynamic api_key
6
6
 
7
+ attr_reader :base_url #: String? # @dynamic base_url
8
+
7
9
  attr_accessor :client #: untyped # @dynamic client, client=
8
10
 
9
11
  #--
10
12
  #: () -> void
11
13
  def initialize
12
14
  @api_key = nil
15
+ @base_url = nil
13
16
  @client = nil
14
17
  end
15
18
 
@@ -18,4 +21,10 @@ class Riffer::Config::Anthropic
18
21
  def api_key=(value)
19
22
  @api_key = Riffer::Helpers::Validate.optional_string(value, attribute: "api_key")
20
23
  end
24
+
25
+ #--
26
+ #: (untyped) -> void
27
+ def base_url=(value)
28
+ @base_url = Riffer::Helpers::Validate.optional_string(value, attribute: "base_url")
29
+ end
21
30
  end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Config::Future
5
+ # Steep can't type an empty literal; drop the ignore once FLAGS has an entry.
6
+ # steep:ignore:start
7
+ FLAGS = {}.freeze #: Hash[Symbol, { default: bool }]
8
+ # steep:ignore:end
9
+
10
+ # @rbs @flags: Hash[Symbol, { default: bool }]
11
+ # @rbs @enabled: Hash[Symbol, bool]
12
+
13
+ #--
14
+ #: (?flags: Hash[Symbol, { default: bool }]) -> void
15
+ def initialize(flags: FLAGS)
16
+ @flags = flags
17
+ @enabled = {}
18
+ flags.each_key { |name| define_singleton_method(:"#{name}=") { |value| set(name, value) } }
19
+ end
20
+
21
+ #--
22
+ #: (Symbol) -> bool
23
+ def enabled?(name)
24
+ flag(name)[:default] || @enabled.fetch(name, false)
25
+ end
26
+
27
+ private
28
+
29
+ #--
30
+ #: (Symbol, untyped) -> void
31
+ def set(name, value)
32
+ graduated = flag(name)[:default]
33
+ enabled = Riffer::Helpers::Boolean.coerce(value, attribute: "config.future.#{name}")
34
+
35
+ if graduated
36
+ Riffer::Deprecation.warn(
37
+ id: :"future_#{name}",
38
+ message: "config.future.#{name} is now the default and setting it has no effect; remove it.",
39
+ )
40
+ end
41
+
42
+ @enabled[name] = enabled
43
+ end
44
+
45
+ #--
46
+ #: (Symbol) -> { default: bool }
47
+ def flag(name)
48
+ @flags.fetch(name) do
49
+ known = @flags.empty? ? "none" : @flags.keys.map(&:inspect).join(", ")
50
+ raise Riffer::ArgumentError, "unknown future flag #{name.inspect} (known flags: #{known})"
51
+ end
52
+ end
53
+ end
@@ -4,12 +4,15 @@
4
4
  class Riffer::Config::Gemini
5
5
  attr_reader :api_key #: String? # @dynamic api_key
6
6
 
7
+ attr_reader :base_url #: String? # @dynamic base_url
8
+
7
9
  attr_accessor :client #: untyped # @dynamic client, client=
8
10
 
9
11
  #--
10
12
  #: () -> void
11
13
  def initialize
12
14
  @api_key = nil
15
+ @base_url = nil
13
16
  @client = nil
14
17
  end
15
18
 
@@ -18,4 +21,10 @@ class Riffer::Config::Gemini
18
21
  def api_key=(value)
19
22
  @api_key = Riffer::Helpers::Validate.optional_string(value, attribute: "api_key")
20
23
  end
24
+
25
+ #--
26
+ #: (untyped) -> void
27
+ def base_url=(value)
28
+ @base_url = Riffer::Helpers::Validate.optional_string(value, attribute: "base_url")
29
+ end
21
30
  end
@@ -0,0 +1,38 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Config::GoogleCloud
5
+ attr_reader :project_id #: String? # @dynamic project_id
6
+
7
+ # The default +"global"+ endpoint routes requests to any region, so it
8
+ # carries no data-residency guarantee.
9
+ attr_reader :location #: String # @dynamic location
10
+
11
+ # A googleauth credentials object; +nil+ resolves Application Default
12
+ # Credentials.
13
+ attr_accessor :credentials #: untyped # @dynamic credentials, credentials=
14
+
15
+ attr_accessor :client #: untyped # @dynamic client, client=
16
+
17
+ #--
18
+ #: () -> void
19
+ def initialize
20
+ @project_id = nil
21
+ @location = "global"
22
+ @credentials = nil
23
+ @client = nil
24
+ end
25
+
26
+ #--
27
+ #: (untyped) -> void
28
+ def project_id=(value)
29
+ @project_id = Riffer::Helpers::Validate.optional_string(value, attribute: "project_id")
30
+ end
31
+
32
+ # +nil+ restores the +"global"+ default.
33
+ #--
34
+ #: (untyped) -> void
35
+ def location=(value)
36
+ @location = Riffer::Helpers::Validate.optional_string(value, attribute: "location") || "global"
37
+ end
38
+ end
@@ -4,11 +4,7 @@
4
4
  # @deprecated Set pricing in a catalog file instead (see docs/CATALOG.md).
5
5
  # A catalog entry's pricing wins over rates registered here.
6
6
  class Riffer::Config::Pricing
7
- DEPRECATION_MESSAGE = "riffer: config.pricing is deprecated; move rates into a catalog file " \
8
- "listed in config.catalog_files (see docs/CATALOG.md)" #: String
9
-
10
7
  # @rbs @rates: Hash[String, Riffer::Catalog::Rates]
11
- # @rbs self.@warned: bool
12
8
 
13
9
  #--
14
10
  #: () -> void
@@ -19,7 +15,11 @@ class Riffer::Config::Pricing
19
15
  #--
20
16
  #: ((String | Array[String]), input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
21
17
  def set(models, input:, output:, cache_read: nil, cache_write: nil)
22
- self.class.warn_deprecated
18
+ Riffer::Deprecation.warn(
19
+ id: :config_pricing,
20
+ message: "config.pricing is deprecated; move rates into a catalog file listed in config.catalog_files " \
21
+ "(see docs/CATALOG.md).",
22
+ )
23
23
 
24
24
  ids = models.is_a?(Array) ? models : [models]
25
25
  raise Riffer::ArgumentError, "at least one model id is required" if ids.empty?
@@ -41,14 +41,4 @@ class Riffer::Config::Pricing
41
41
  def empty?
42
42
  @rates.empty?
43
43
  end
44
-
45
- # Once per process, so a boot that sets many models logs one line.
46
- #--
47
- #: () -> void
48
- def self.warn_deprecated
49
- return if @warned
50
-
51
- @warned = true
52
- Kernel.warn(DEPRECATION_MESSAGE)
53
- end
54
44
  end
data/lib/riffer/config.rb CHANGED
@@ -14,6 +14,8 @@ class Riffer::Config
14
14
 
15
15
  attr_reader :gemini #: Riffer::Config::Gemini # @dynamic gemini
16
16
 
17
+ attr_reader :google_cloud #: Riffer::Config::GoogleCloud # @dynamic google_cloud
18
+
17
19
  attr_reader :openai #: Riffer::Config::OpenAI # @dynamic openai
18
20
 
19
21
  attr_reader :openrouter #: Riffer::Config::OpenRouter # @dynamic openrouter
@@ -43,6 +45,8 @@ class Riffer::Config
43
45
 
44
46
  attr_reader :files #: Riffer::Config::Files # @dynamic files
45
47
 
48
+ attr_reader :future #: Riffer::Config::Future # @dynamic future
49
+
46
50
  # @deprecated Use +catalog_files+.
47
51
  attr_reader :pricing #: Riffer::Config::Pricing # @dynamic pricing
48
52
 
@@ -84,6 +88,18 @@ class Riffer::Config
84
88
  @message_id_strategy = value
85
89
  end
86
90
 
91
+ attr_reader :deprecations #: (Symbol | ^(Riffer::Deprecation::Event) -> void) # @dynamic deprecations
92
+
93
+ #--
94
+ #: ((Symbol | ^(Riffer::Deprecation::Event) -> void)) -> void
95
+ def deprecations=(value)
96
+ unless Riffer::Deprecation::MODES.include?(value) || value.respond_to?(:call)
97
+ raise Riffer::ArgumentError,
98
+ "deprecations must be one of #{Riffer::Deprecation::MODES.inspect} or a callable, got #{value.inspect}"
99
+ end
100
+ @deprecations = value
101
+ end
102
+
87
103
  #--
88
104
  #: () -> void
89
105
  def initialize
@@ -91,6 +107,7 @@ class Riffer::Config
91
107
  @anthropic = Anthropic.new
92
108
  @azure_openai = AzureOpenAI.new
93
109
  @gemini = Gemini.new
110
+ @google_cloud = GoogleCloud.new
94
111
  @openai = OpenAI.new
95
112
  @openrouter = OpenRouter.new
96
113
  @evals = Evals.new
@@ -99,9 +116,11 @@ class Riffer::Config
99
116
  @skills = Skills.new
100
117
  @tracing = Tracing.new
101
118
  @files = Files.new
119
+ @future = Future.new
102
120
  @pricing = Pricing.new
103
121
  no_files = [] #: Array[String]
104
122
  @catalog_files = no_files.freeze
105
123
  @message_id_strategy = :none
124
+ @deprecations = :warn
106
125
  end
107
126
  end
@@ -0,0 +1,25 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Deprecation::Event
5
+ attr_reader :id #: Symbol # @dynamic id
6
+
7
+ attr_reader :message #: String # @dynamic message
8
+
9
+ attr_reader :location #: String? # @dynamic location
10
+
11
+ #--
12
+ #: (id: Symbol, message: String, location: String?) -> void
13
+ def initialize(id:, message:, location:)
14
+ @id = id
15
+ @message = message
16
+ @location = location
17
+ end
18
+
19
+ #--
20
+ #: () -> String
21
+ def to_s
22
+ text = "riffer: #{message}"
23
+ location ? "#{text} Called from #{location}." : text
24
+ end
25
+ end
@@ -0,0 +1,60 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Riffer::Deprecation
5
+ extend self
6
+
7
+ # @rbs @mutex: Thread::Mutex
8
+ # @rbs @reported: Set[[Symbol, String?]]
9
+
10
+ MODES = %i[warn raise silence].freeze #: Array[Symbol]
11
+
12
+ LIB_DIR = "#{File.dirname(__FILE__, 2)}/".freeze #: String
13
+ ALLOWED_KEY = :riffer_deprecations_allowed #: Symbol
14
+ private_constant :LIB_DIR, :ALLOWED_KEY
15
+
16
+ @mutex = Mutex.new
17
+ @reported = Set.new
18
+
19
+ #--
20
+ #: (id: Symbol, message: String) -> void
21
+ def warn(id:, message:)
22
+ return if Fiber[ALLOWED_KEY]
23
+
24
+ frame = caller_locations&.find { |location| !location.path.to_s.start_with?(LIB_DIR) }
25
+ location = frame && "#{frame.path}:#{frame.lineno}"
26
+ event = Event.new(id: id, message: message, location: location)
27
+
28
+ case (handler = Riffer.config.deprecations)
29
+ when :silence then nil
30
+ # Every call, not once per line, so a suite in :raise mode fails on each offending test.
31
+ when :raise then raise Riffer::DeprecationError, event.to_s
32
+ when :warn then Kernel.warn(event.to_s) if first_report?(event)
33
+ else
34
+ callable = handler #: ^(Event) -> void
35
+ callable.call(event) if first_report?(event)
36
+ end
37
+ end
38
+
39
+ #--
40
+ #: [T] () { () -> T } -> T
41
+ def allow
42
+ previous = Fiber[ALLOWED_KEY] #: bool?
43
+ # Fiber storage is inherited by threads and fibers spawned inside the block,
44
+ # so work the block fans out stays silenced while other threads are not.
45
+ Fiber[ALLOWED_KEY] = true
46
+ begin
47
+ yield
48
+ ensure
49
+ Fiber[ALLOWED_KEY] = previous
50
+ end
51
+ end
52
+
53
+ private
54
+
55
+ #--
56
+ #: (Event) -> bool
57
+ def first_report?(event)
58
+ !@mutex.synchronize { @reported.add?([event.id, event.location]) }.nil?
59
+ end
60
+ end
@@ -0,0 +1,141 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ require "faraday"
5
+ require "json"
6
+
7
+ class Riffer::HTTP::Client
8
+ # @rbs @connection: Faraday::Connection
9
+ # @rbs @extra_headers: Hash[String, String]
10
+
11
+ DEFAULT_OPEN_TIMEOUT = 10 #: Integer
12
+ DEFAULT_READ_TIMEOUT = 600 #: Integer
13
+
14
+ # +headers+ are sent on every request and win over the subclass's auth and
15
+ # version headers, as do headers set on the +connection+.
16
+ #--
17
+ #: (?headers: Hash[String, String], ?connection: Faraday::Connection?) -> void
18
+ def initialize(headers: {}, connection: nil)
19
+ @extra_headers = headers
20
+ @connection = connection || Faraday.new(
21
+ request: { open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT },
22
+ )
23
+ end
24
+
25
+ # Raises Riffer::APIError on a non-success status.
26
+ #--
27
+ #: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
28
+ def post(path, body)
29
+ response = request(path, body)
30
+ raise_api_error!(response.status, response.body) unless response.success?
31
+ JSON.parse(response.body, symbolize_names: true)
32
+ end
33
+
34
+ # Raises Riffer::APIError on a non-success status; the error body is never yielded.
35
+ #--
36
+ #: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
37
+ def post_stream(path, body, &)
38
+ streamed = false
39
+ yielded = false
40
+ held = +""
41
+
42
+ # A proc, not a lambda: httpx and typhoeus pass no env. Without one the
43
+ # status is unknown until the response returns, so every chunk is held.
44
+ on_data = proc do |chunk, bytes_received, env|
45
+ streamed = true
46
+ # Faraday restarts bytes_received on each attempt. httpx passes the chunk
47
+ # size instead, so attempts are only told apart when there is an env.
48
+ if env && bytes_received == chunk.bytesize
49
+ if yielded
50
+ raise Riffer::Error, "the stream restarted after data was delivered; " \
51
+ "retry middleware must not retry streaming requests mid-body"
52
+ end
53
+ held.clear
54
+ end
55
+
56
+ if env&.success?
57
+ unless chunk.empty?
58
+ yielded = true
59
+ yield(chunk)
60
+ end
61
+ else
62
+ held << chunk
63
+ end
64
+ end
65
+
66
+ response = request(path, body, on_data: on_data)
67
+ unyielded = streamed ? held : response.body
68
+ raise_api_error!(response.status, unyielded) unless response.success?
69
+ yield(unyielded) unless unyielded.empty?
70
+ end
71
+
72
+ private
73
+
74
+ #--
75
+ #: (String) -> String
76
+ def url_for(path)
77
+ raise NotImplementedError, "Subclasses must implement #url_for"
78
+ end
79
+
80
+ # Called per request so short-lived credentials can refresh.
81
+ #--
82
+ #: () -> Hash[String, String]
83
+ def headers
84
+ raise NotImplementedError, "Subclasses must implement #headers"
85
+ end
86
+
87
+ #--
88
+ #: () -> String
89
+ def error_label
90
+ raise NotImplementedError, "Subclasses must implement #error_label"
91
+ end
92
+
93
+ #--
94
+ #: (Hash[Symbol, untyped], String) -> String
95
+ def error_message(parsed, raw)
96
+ error = parsed[:error]
97
+ case error
98
+ when Hash then error[:message] || parsed[:message] || raw
99
+ when String then error
100
+ else parsed[:message] || raw
101
+ end
102
+ end
103
+
104
+ # Headers go on the request, never on the connection, which may be shared
105
+ # across fibers and keeps whatever headers the caller configured on it.
106
+ # Faraday matches header names case-insensitively, so a caller's header
107
+ # replaces the subclass's whatever its casing. The content and encoding
108
+ # headers below are always riffer's: the body and the stream depend on them.
109
+ #--
110
+ #: (String, Hash[Symbol, untyped], ?on_data: Proc?) -> Faraday::Response
111
+ def request(path, body, on_data: nil)
112
+ @connection.post(url_for(path)) do |req|
113
+ req.headers.update(@extra_headers)
114
+ headers.each { |name, value| req.headers[name] ||= value }
115
+ req.headers["content-type"] = "application/json"
116
+ if on_data
117
+ req.headers["accept"] = "text/event-stream"
118
+ # Net::HTTP buffers a gzip body until EOF, which stalls the stream.
119
+ req.headers["accept-encoding"] = "identity"
120
+ req.options.on_data = on_data
121
+ end
122
+ req.body = body.to_json
123
+ end
124
+ end
125
+
126
+ #--
127
+ #: (Integer, String) -> bot
128
+ def raise_api_error!(status, raw)
129
+ parsed = begin
130
+ JSON.parse(raw, symbolize_names: true)
131
+ rescue JSON::ParserError
132
+ nil
133
+ end
134
+ # Vertex AI wraps its error object in a one-element array.
135
+ parsed = parsed.first if parsed.is_a?(Array) && parsed.length == 1
136
+ fields = parsed.is_a?(Hash) ? parsed : {} #: Hash[Symbol, untyped]
137
+
138
+ message = "#{error_label} API error (#{status}): #{error_message(fields, raw)}"
139
+ raise Riffer::APIError.new(message, status: status, body: raw)
140
+ end
141
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Riffer::HTTP
5
+ end
@@ -8,7 +8,6 @@ class Riffer::Mcp::Client
8
8
  #: (endpoint: String, ?headers: (Hash[String, String] | Proc), ?client: untyped?) -> void
9
9
  def initialize(endpoint:, headers: {}, client: nil)
10
10
  depends_on "mcp"
11
- depends_on "faraday"
12
11
 
13
12
  @client = client || begin
14
13
  resolved_headers = Riffer::Helpers::CallOrValue.resolve(headers)