riffer 0.56.0 → 0.57.1

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/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +26 -0
  4. data/README.md +1 -1
  5. data/docs/AGENTS.md +105 -50
  6. data/docs/AGENT_LIFECYCLE.md +1 -1
  7. data/docs/CONFIGURATION.md +7 -3
  8. data/docs/EVALS.md +2 -0
  9. data/docs/MCP.md +36 -0
  10. data/docs/MESSAGES.md +13 -0
  11. data/docs/OVERVIEW.md +7 -7
  12. data/docs/SERIALIZATION.md +12 -2
  13. data/docs/SKILLS.md +1 -1
  14. data/docs/STABILITY.md +1 -1
  15. data/docs/TOOLS.md +93 -37
  16. data/docs/TOOL_ADVANCED.md +7 -0
  17. data/docs/providers/AMAZON_BEDROCK.md +6 -2
  18. data/docs/providers/ANTHROPIC.md +35 -2
  19. data/docs/providers/AZURE_OPENAI.md +9 -3
  20. data/docs/providers/CUSTOM_PROVIDERS.md +19 -0
  21. data/docs/providers/GEMINI.md +8 -4
  22. data/docs/providers/GOOGLE_CLOUD.md +10 -5
  23. data/docs/providers/MOCK_PROVIDER.md +2 -0
  24. data/docs/providers/OPENAI.md +25 -3
  25. data/docs/providers/OPENROUTER.md +11 -3
  26. data/docs/providers/PROVIDERS.md +1 -1
  27. data/docs-site/index.html.erb +1 -1
  28. data/lib/riffer/agent/config.rb +21 -0
  29. data/lib/riffer/agent/context.rb +36 -18
  30. data/lib/riffer/agent/run.rb +54 -8
  31. data/lib/riffer/agent/serializer.rb +5 -0
  32. data/lib/riffer/agent/session.rb +1 -0
  33. data/lib/riffer/agent.rb +43 -0
  34. data/lib/riffer/config/mcp.rb +17 -0
  35. data/lib/riffer/config/pricing.rb +2 -2
  36. data/lib/riffer/config.rb +12 -1
  37. data/lib/riffer/evals/evaluator.rb +8 -1
  38. data/lib/riffer/evals/evaluator_runner.rb +1 -0
  39. data/lib/riffer/evals/judge.rb +2 -2
  40. data/lib/riffer/evals.rb +2 -0
  41. data/lib/riffer/mcp/search_tool.rb +1 -1
  42. data/lib/riffer/mcp.rb +7 -0
  43. data/lib/riffer/messages/tool.rb +6 -2
  44. data/lib/riffer/params/any_of.rb +5 -8
  45. data/lib/riffer/params/boolean.rb +1 -1
  46. data/lib/riffer/params/param.rb +96 -67
  47. data/lib/riffer/params.rb +50 -71
  48. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +3 -10
  49. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +89 -13
  50. data/lib/riffer/providers/anthropic_vertex.rb +7 -0
  51. data/lib/riffer/providers/base.rb +43 -7
  52. data/lib/riffer/providers/deferred_tool_gateway/sink.rb +54 -0
  53. data/lib/riffer/providers/deferred_tool_gateway/tool.rb +17 -0
  54. data/lib/riffer/providers/deferred_tool_gateway.rb +150 -0
  55. data/lib/riffer/providers/gemini.rb +5 -5
  56. data/lib/riffer/providers/mock.rb +6 -0
  57. data/lib/riffer/providers/open_ai.rb +38 -10
  58. data/lib/riffer/skills/activate_tool.rb +1 -1
  59. data/lib/riffer/tool.rb +92 -2
  60. data/lib/riffer/tools/response.rb +11 -2
  61. data/lib/riffer/version.rb +1 -1
  62. data/sig/generated/riffer/agent/config.rbs +13 -1
  63. data/sig/generated/riffer/agent/context.rbs +16 -0
  64. data/sig/generated/riffer/agent/run.rbs +14 -2
  65. data/sig/generated/riffer/agent.rbs +13 -0
  66. data/sig/generated/riffer/config/mcp.rbs +7 -0
  67. data/sig/generated/riffer/config.rbs +5 -1
  68. data/sig/generated/riffer/evals/evaluator.rbs +4 -0
  69. data/sig/generated/riffer/evals.rbs +1 -0
  70. data/sig/generated/riffer/mcp.rbs +1 -0
  71. data/sig/generated/riffer/messages/tool.rbs +4 -2
  72. data/sig/generated/riffer/params/any_of.rbs +4 -4
  73. data/sig/generated/riffer/params/boolean.rbs +1 -1
  74. data/sig/generated/riffer/params/param.rbs +28 -14
  75. data/sig/generated/riffer/params.rbs +20 -20
  76. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +2 -5
  77. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +34 -2
  78. data/sig/generated/riffer/providers/anthropic_vertex.rbs +5 -0
  79. data/sig/generated/riffer/providers/base.rbs +13 -0
  80. data/sig/generated/riffer/providers/deferred_tool_gateway/sink.rbs +23 -0
  81. data/sig/generated/riffer/providers/deferred_tool_gateway/tool.rbs +4 -0
  82. data/sig/generated/riffer/providers/deferred_tool_gateway.rbs +58 -0
  83. data/sig/generated/riffer/providers/mock.rbs +4 -0
  84. data/sig/generated/riffer/providers/open_ai.rbs +16 -4
  85. data/sig/generated/riffer/tool.rbs +48 -2
  86. data/sig/generated/riffer/tools/response.rbs +9 -2
  87. data/sig/manual/riffer/providers/deferred_tool_gateway.rbs +5 -0
  88. metadata +8 -3
  89. data/lib/riffer/tools/toolable.rb +0 -113
  90. data/sig/generated/riffer/tools/toolable.rbs +0 -66
@@ -4,6 +4,7 @@
4
4
  class Riffer::Agent::Config
5
5
  DEFAULT_MAX_STEPS = 16 #: Integer
6
6
  STRUCTURED_OUTPUT_STRATEGIES = %i[native prompted].freeze #: Array[Symbol]
7
+ DEFERRED_TOOLS_STRATEGIES = %i[native gateway].freeze #: Array[Symbol]
7
8
 
8
9
  REASONING_LEVELS = %i[off low medium high xhigh max].freeze #: Array[Symbol]
9
10
 
@@ -18,6 +19,8 @@ class Riffer::Agent::Config
18
19
  attr_accessor :max_steps #: Numeric? # @dynamic max_steps, max_steps=
19
20
  attr_reader :reasoning #: Symbol? # @dynamic reasoning
20
21
  attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic tools_config, tools_config=
22
+ attr_accessor :deferred_tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic deferred_tools_config, deferred_tools_config=
23
+ attr_reader :deferred_tools_strategy #: Symbol # @dynamic deferred_tools_strategy
21
24
  attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]] # @dynamic mcp_configs
22
25
  attr_accessor :skills_config #: Riffer::Skills::Config? # @dynamic skills_config, skills_config=
23
26
  attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]] # @dynamic guardrails
@@ -33,6 +36,8 @@ class Riffer::Agent::Config
33
36
  # ?max_steps: Numeric?,
34
37
  # ?reasoning: (Symbol | String)?,
35
38
  # ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
39
+ # ?deferred_tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
40
+ # ?deferred_tools_strategy: Symbol,
36
41
  # ?mcp_configs: Array[Hash[Symbol, untyped]],
37
42
  # ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
38
43
  # ?skills_config: Riffer::Skills::Config?,
@@ -48,6 +53,8 @@ class Riffer::Agent::Config
48
53
  max_steps: DEFAULT_MAX_STEPS,
49
54
  reasoning: nil,
50
55
  tools_config: nil,
56
+ deferred_tools_config: nil,
57
+ deferred_tools_strategy: :native,
51
58
  mcp_configs: [],
52
59
  tool_runtime: nil,
53
60
  skills_config: nil,
@@ -56,6 +63,7 @@ class Riffer::Agent::Config
56
63
  @model_options = model_options
57
64
  @max_steps = max_steps
58
65
  @tools_config = tools_config
66
+ @deferred_tools_config = deferred_tools_config
59
67
  @mcp_configs = mcp_configs
60
68
  @skills_config = skills_config
61
69
  @guardrails = guardrails
@@ -64,6 +72,7 @@ class Riffer::Agent::Config
64
72
  self.instructions = instructions
65
73
  self.structured_output = structured_output
66
74
  self.structured_output_strategy = structured_output_strategy
75
+ self.deferred_tools_strategy = deferred_tools_strategy
67
76
  self.reasoning = reasoning
68
77
  self.tool_runtime = tool_runtime if tool_runtime
69
78
  end
@@ -95,6 +104,17 @@ class Riffer::Agent::Config
95
104
  @structured_output_strategy = value
96
105
  end
97
106
 
107
+ #--
108
+ #: (Symbol) -> Symbol
109
+ def deferred_tools_strategy=(value)
110
+ unless DEFERRED_TOOLS_STRATEGIES.include?(value)
111
+ raise Riffer::ArgumentError,
112
+ "deferred_tools_strategy must be one of #{DEFERRED_TOOLS_STRATEGIES.inspect}, got #{value.inspect}"
113
+ end
114
+
115
+ @deferred_tools_strategy = value
116
+ end
117
+
98
118
  #--
99
119
  #: ((Symbol | String)?) -> Symbol?
100
120
  def reasoning=(value)
@@ -189,6 +209,7 @@ class Riffer::Agent::Config
189
209
  @mcp_configs = Riffer::Helpers::DeepDup.call(source.mcp_configs)
190
210
  @guardrails = Riffer::Helpers::DeepDup.call(source.guardrails)
191
211
  @tools_config = Riffer::Helpers::DeepDup.call(source.tools_config)
212
+ @deferred_tools_config = Riffer::Helpers::DeepDup.call(source.deferred_tools_config)
192
213
  @skills_config = source.skills_config&.dup
193
214
  @structured_output = source.structured_output&.dup
194
215
  end
@@ -15,12 +15,14 @@ class Riffer::Agent::Context
15
15
  raise Riffer::ArgumentError,
16
16
  "Reserved keys cannot be passed in context: #{reserved.join(', ')}"
17
17
  end
18
+ warn_deferred_tools_key if data.key?(:deferred_tools)
18
19
 
19
20
  @data = data.dup
20
21
  @data[:skills] = nil
21
22
  @data[:token_usage] = nil
22
23
  @data[:mcp_progressive_tools] = nil
23
24
  @data[:discovered_tools] = nil
25
+ @deferred_tools = nil
24
26
  end
25
27
 
26
28
  #--
@@ -71,15 +73,7 @@ class Riffer::Agent::Context
71
73
  #--
72
74
  #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
73
75
  def mcp_progressive_tools=(value)
74
- valid = value.nil? || (
75
- value.is_a?(Array) &&
76
- value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
77
- )
78
- unless valid
79
- raise Riffer::ArgumentError,
80
- "mcp_progressive_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
81
- end
82
- @data[:mcp_progressive_tools] = value
76
+ @data[:mcp_progressive_tools] = validate_tool_classes(:mcp_progressive_tools, value)
83
77
  end
84
78
 
85
79
  #--
@@ -91,15 +85,15 @@ class Riffer::Agent::Context
91
85
  #--
92
86
  #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
93
87
  def discovered_tools=(value)
94
- valid = value.nil? || (
95
- value.is_a?(Array) &&
96
- value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
97
- )
98
- unless valid
99
- raise Riffer::ArgumentError,
100
- "discovered_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
101
- end
102
- @data[:discovered_tools] = value
88
+ @data[:discovered_tools] = validate_tool_classes(:discovered_tools, value)
89
+ end
90
+
91
+ attr_reader :deferred_tools #: Array[singleton(Riffer::Tool)]? # @dynamic deferred_tools
92
+
93
+ #--
94
+ #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
95
+ def deferred_tools=(value)
96
+ @deferred_tools = validate_tool_classes(:deferred_tools, value)
103
97
  end
104
98
 
105
99
  #--
@@ -120,4 +114,28 @@ class Riffer::Agent::Context
120
114
  def to_h
121
115
  @data.dup
122
116
  end
117
+
118
+ private
119
+
120
+ #--
121
+ #: (Symbol, Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
122
+ def validate_tool_classes(name, value)
123
+ valid = value.nil? || (value.is_a?(Array) && value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool })
124
+ unless valid
125
+ raise Riffer::ArgumentError,
126
+ "#{name} must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
127
+ end
128
+
129
+ value
130
+ end
131
+
132
+ #--
133
+ #: () -> void
134
+ def warn_deferred_tools_key
135
+ Riffer::Deprecation.warn(
136
+ id: :context_deferred_tools_key,
137
+ message: "Passing :deferred_tools in context: is deprecated; a future breaking release reserves the key " \
138
+ "for the agent's deferred tools (context.deferred_tools). Rename the key.",
139
+ )
140
+ end
123
141
  end
@@ -277,17 +277,29 @@ module Riffer::Agent::Run
277
277
  def execute_tool_calls(agent, assistant_message, tool_calls: assistant_message.tool_calls, tags: {})
278
278
  return if tool_calls.empty?
279
279
 
280
- results = agent.tool_runtime.execute(
281
- tool_calls,
282
- tools: effective_tools(agent),
280
+ # Only from earlier turns: the model made every call in this one before seeing any of its loads, even when a
281
+ # resumed turn already has some of its results in the session.
282
+ earlier = agent.session.messages.take_while { |message| !message.equal?(assistant_message) }
283
+ loaded = loaded_tools(earlier, agent.deferred_tools)
284
+ unloaded_names = (agent.deferred_tools - loaded).map(&:name)
285
+ # Refused here rather than by the runtime, since a custom runtime may ignore +tools:+.
286
+ refused, callable = tool_calls.partition { |tool_call| unloaded_names.include?(tool_call.name) }
287
+
288
+ dispatched = agent.tool_runtime.execute(
289
+ callable,
290
+ tools: effective_tools(agent) + loaded,
283
291
  context: agent.context,
284
292
  assistant_message: assistant_message,
285
293
  tags: tags,
286
- )
294
+ ).to_h { |tool_call, result| [tool_call, reject_invalid_load(agent, result)] }
287
295
 
288
- inject_discovered_tools(agent, results)
296
+ inject_discovered_tools(agent, dispatched)
297
+
298
+ results = dispatched.merge(refused.to_h { |tool_call| [tool_call, tool_not_loaded(tool_call)] })
299
+ tool_calls.each do |tool_call|
300
+ result = results.fetch(tool_call, nil)
301
+ next unless result
289
302
 
290
- results.each do |tool_call, result|
291
303
  agent.session.add(
292
304
  Riffer::Messages::Tool.new(
293
305
  result.content,
@@ -295,15 +307,45 @@ module Riffer::Agent::Run
295
307
  name: tool_call.name,
296
308
  error: result.error_message,
297
309
  error_type: result.error_type,
310
+ loaded_tools: result.loaded_tools.map(&:name),
298
311
  ),
299
312
  )
300
313
  end
301
314
  end
302
315
 
303
316
  #--
304
- #: (Riffer::Agent, Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]) -> void
317
+ #: (Array[Riffer::Messages::Base], Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
318
+ def loaded_tools(messages, deferred_tools)
319
+ return [] if deferred_tools.empty?
320
+
321
+ tool_messages = messages.grep(Riffer::Messages::Tool) #: Array[Riffer::Messages::Tool]
322
+ names = tool_messages.reject(&:error?).flat_map(&:loaded_tools)
323
+ # By name, since an agent rebuilt with +from_h+ holds body-less shells rather than the original classes.
324
+ deferred_tools.select { |tool| names.include?(tool.name) }
325
+ end
326
+
327
+ #--
328
+ #: (Riffer::Agent, Riffer::Tools::Response) -> Riffer::Tools::Response
329
+ def reject_invalid_load(agent, result)
330
+ invalid = result.loaded_tools.map(&:name) - agent.deferred_tools.map(&:name)
331
+ return result if invalid.empty?
332
+
333
+ Riffer::Tools::Response.error(
334
+ "Cannot load #{invalid.join(', ')}: only this agent's deferred tools can be loaded",
335
+ type: :invalid_tool_load,
336
+ )
337
+ end
338
+
339
+ #--
340
+ #: (Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
341
+ def tool_not_loaded(tool_call)
342
+ Riffer::Tools::Response.error("Tool '#{tool_call.name}' has not been loaded", type: :tool_not_loaded)
343
+ end
344
+
345
+ #--
346
+ #: (Riffer::Agent, Hash[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]) -> void
305
347
  def inject_discovered_tools(agent, results)
306
- to_inject = results.flat_map do |_, result|
348
+ to_inject = results.values.flat_map do |result|
307
349
  result.is_a?(Riffer::Mcp::SearchTool::Result) ? result.discovered_tools : [] #: Array[singleton(Riffer::Tool)]
308
350
  end
309
351
  return if to_inject.empty?
@@ -371,6 +413,10 @@ module Riffer::Agent::Run
371
413
  opts[:structured_output] = agent.structured_output if agent.structured_output
372
414
  reasoning = agent.config.reasoning
373
415
  opts[:riffer_reasoning_level] = reasoning if reasoning
416
+ unless agent.deferred_tools.empty?
417
+ opts[:deferred_tools] = agent.deferred_tools
418
+ opts[:riffer_deferred_tools_strategy] = agent.config.deferred_tools_strategy
419
+ end
374
420
  # Providers extract :tags for native request metadata; it never reaches an
375
421
  # SDK call verbatim.
376
422
  opts[:tags] = tags unless tags.empty?
@@ -30,6 +30,8 @@ module Riffer::Agent::Serializer
30
30
  structured_output_strategy: config.structured_output_strategy,
31
31
  reasoning: config.reasoning,
32
32
  tools: agent.tools.map { |tool_class| tool_descriptor(tool_class) },
33
+ deferred_tools: agent.deferred_tools.map { |tool_class| tool_descriptor(tool_class) },
34
+ deferred_tools_strategy: config.deferred_tools_strategy,
33
35
  }
34
36
  end
35
37
 
@@ -71,6 +73,7 @@ module Riffer::Agent::Serializer
71
73
  #: (Hash[Symbol, untyped], context: Hash[Symbol, untyped]?, session: Riffer::Agent::Session?, tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
72
74
  def decode_v1(hash, context:, session:, tool_resolver:, tool_runtime:)
73
75
  tools = Array(hash[:tools]).map { |descriptor| tool_resolver.call(descriptor) }
76
+ deferred_tools = Array(hash[:deferred_tools]).map { |descriptor| tool_resolver.call(descriptor) }
74
77
 
75
78
  config_args = {
76
79
  identifier: hash[:identifier],
@@ -82,6 +85,8 @@ module Riffer::Agent::Serializer
82
85
  max_steps: decode_max_steps(hash),
83
86
  reasoning: hash[:reasoning],
84
87
  tools_config: tools,
88
+ deferred_tools_config: deferred_tools,
89
+ deferred_tools_strategy: (hash[:deferred_tools_strategy] || :native).to_sym,
85
90
  } #: Hash[Symbol, untyped]
86
91
  # Config#tool_runtime= rejects nil.
87
92
  config_args[:tool_runtime] = tool_runtime if tool_runtime
@@ -200,6 +200,7 @@ class Riffer::Agent::Session
200
200
  id: attrs.fetch(:id, old.id),
201
201
  error: attrs.fetch(:error, old.error),
202
202
  error_type: attrs.fetch(:error_type, old.error_type),
203
+ loaded_tools: attrs.fetch(:loaded_tools, old.loaded_tools),
203
204
  )
204
205
  when Riffer::Messages::User
205
206
  Riffer::Messages::User.new(
data/lib/riffer/agent.rb CHANGED
@@ -86,10 +86,25 @@ class Riffer::Agent
86
86
  value.nil? ? config.tools_config : (config.tools_config = value)
87
87
  end
88
88
 
89
+ #--
90
+ #: (?(Array[singleton(Riffer::Tool)] | Proc)?, ?strategy: Symbol?) -> (Array[singleton(Riffer::Tool)] | Proc)?
91
+ def self.deferred_tools(value = nil, strategy: nil)
92
+ config.deferred_tools_config = value if value
93
+ config.deferred_tools_strategy = strategy if strategy
94
+ config.deferred_tools_config
95
+ end
96
+
97
+ # @deprecated MCP client support will be removed; wrap the +mcp+ gem in your own Riffer::Tool (see docs/MCP.md).
89
98
  # +progressive+ exposes +mcp_search+ instead of every tool schema up front.
90
99
  #--
91
100
  #: (String | Symbol, ?progressive: bool) -> void
92
101
  def self.use_mcp(tag, progressive: true)
102
+ Riffer::Deprecation.warn(
103
+ id: :use_mcp,
104
+ message: "use_mcp is deprecated; MCP client support will be removed in a future release. " \
105
+ "Wrap the mcp gem in your own Riffer::Tool instead (see docs/MCP.md).",
106
+ )
107
+
93
108
  config.add_mcp(tag, progressive: progressive)
94
109
  end
95
110
 
@@ -203,6 +218,7 @@ class Riffer::Agent
203
218
 
204
219
  @structured_output = resolve_structured_output
205
220
  @tools = resolve_tools
221
+ @context.deferred_tools = resolve_deferred_tools
206
222
  @tool_runtime = resolve_tool_runtime
207
223
 
208
224
  @instruction_message = build_instruction_message
@@ -220,6 +236,12 @@ class Riffer::Agent
220
236
  config.identifier || self.class.identifier
221
237
  end
222
238
 
239
+ #--
240
+ #: () -> Array[singleton(Riffer::Tool)]
241
+ def deferred_tools
242
+ @context.deferred_tools || []
243
+ end
244
+
223
245
  #--
224
246
  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
225
247
  def generate(prompt = nil, files: nil, tags: {})
@@ -362,6 +384,27 @@ class Riffer::Agent
362
384
  tools
363
385
  end
364
386
 
387
+ #--
388
+ #: () -> Array[singleton(Riffer::Tool)]
389
+ def resolve_deferred_tools
390
+ deferred = Riffer::Helpers::CallOrValue.resolve(@config.deferred_tools_config, context: @context, default: [])
391
+ return deferred if deferred.empty?
392
+
393
+ gateway = @config.deferred_tools_strategy == :gateway
394
+ unless gateway || @provider.class.supports_deferred_tools?
395
+ raise Riffer::ArgumentError,
396
+ "Provider #{@provider_name} does not support deferred tools natively; " \
397
+ "use deferred_tools(..., strategy: :gateway) to load them through a gateway tool"
398
+ end
399
+
400
+ tools = @tools + (@context.mcp_progressive_tools || []) + deferred
401
+ # The gateway goes on every request alongside the agent's tools, so no tool can share its name.
402
+ tools += [Riffer::Providers::DeferredToolGateway::Tool] if gateway
403
+ assert_distinct_tool_names!(tools)
404
+ deferred.each(&:validate_as_tool!)
405
+ deferred
406
+ end
407
+
365
408
  #--
366
409
  #: () -> Riffer::Tools::Runtime
367
410
  def resolve_tool_runtime
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
  # rbs_inline: enabled
3
3
 
4
+ # @deprecated MCP client support will be removed; wrap the +mcp+ gem in your own Riffer::Tool (see docs/MCP.md).
4
5
  class Riffer::Config::Mcp
5
6
  attr_reader :credentials #: untyped # @dynamic credentials
6
7
 
@@ -16,6 +17,8 @@ class Riffer::Config::Mcp
16
17
  #--
17
18
  #: (untyped) -> void
18
19
  def credentials=(value)
20
+ warn_deprecated
21
+
19
22
  unless value.nil? || value.respond_to?(:call)
20
23
  raise Riffer::ArgumentError, "credentials must respond to #call or be nil"
21
24
  end
@@ -26,6 +29,20 @@ class Riffer::Config::Mcp
26
29
  #--
27
30
  #: (untyped) -> void
28
31
  def discovery_runner=(value)
32
+ warn_deprecated
33
+
29
34
  @discovery_runner = Riffer::Helpers::Validate.runner(value, attribute: "discovery_runner")
30
35
  end
36
+
37
+ private
38
+
39
+ #--
40
+ #: () -> void
41
+ def warn_deprecated
42
+ Riffer::Deprecation.warn(
43
+ id: :config_mcp,
44
+ message: "config.mcp is deprecated; MCP client support will be removed in a future release. " \
45
+ "Wrap the mcp gem in your own Riffer::Tool instead (see docs/MCP.md).",
46
+ )
47
+ end
31
48
  end
@@ -17,8 +17,8 @@ class Riffer::Config::Pricing
17
17
  def set(models, input:, output:, cache_read: nil, cache_write: nil)
18
18
  Riffer::Deprecation.warn(
19
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).",
20
+ message: "config.pricing is deprecated and will be removed in a future version; move rates into a catalog " \
21
+ "file listed in config.catalog_files (see docs/CATALOG.md).",
22
22
  )
23
23
 
24
24
  ids = models.is_a?(Array) ? models : [models]
data/lib/riffer/config.rb CHANGED
@@ -20,7 +20,18 @@ class Riffer::Config
20
20
 
21
21
  attr_reader :openrouter #: Riffer::Config::OpenRouter # @dynamic openrouter
22
22
 
23
- attr_reader :evals #: Riffer::Config::Evals # @dynamic evals
23
+ # @rbs @evals: Riffer::Config::Evals
24
+
25
+ #--
26
+ #: () -> Riffer::Config::Evals
27
+ def evals
28
+ Riffer::Deprecation.warn(
29
+ id: :config_evals,
30
+ message: "config.evals is deprecated and will move out of riffer into the riffer-evals gem " \
31
+ "(see docs/EVALS.md).",
32
+ )
33
+ @evals
34
+ end
24
35
 
25
36
  attr_reader :mcp #: Riffer::Config::Mcp # @dynamic mcp
26
37
 
@@ -49,6 +49,13 @@ class Riffer::Evals::Evaluator
49
49
 
50
50
  private
51
51
 
52
+ #--
53
+ #: (Class) -> void
54
+ def inherited(subclass)
55
+ super
56
+ Riffer::Deprecation.warn(id: :evals, message: Riffer::Evals::DEPRECATION_MESSAGE)
57
+ end
58
+
52
59
  #--
53
60
  #: () -> String
54
61
  def derived_identifier
@@ -100,7 +107,7 @@ class Riffer::Evals::Evaluator
100
107
  #: () -> Riffer::Evals::Judge
101
108
  def judge
102
109
  @judge ||= begin
103
- model = self.class.judge_model || Riffer.config.evals.judge_model
110
+ model = Riffer::Deprecation.allow { self.class.judge_model || Riffer.config.evals.judge_model }
104
111
  unless model
105
112
  raise Riffer::ArgumentError,
106
113
  "No judge model configured. Set judge_model on the evaluator or Riffer.config.evals.judge_model"
@@ -7,6 +7,7 @@ module Riffer::Evals::EvaluatorRunner
7
7
  #--
8
8
  #: (agent: singleton(Riffer::Agent), scenarios: Array[Hash[Symbol, untyped]], evaluators: Array[singleton(Riffer::Evals::Evaluator)], ?context: Hash[Symbol, untyped]?) -> Riffer::Evals::RunResult
9
9
  def run(agent:, scenarios:, evaluators:, context: nil)
10
+ Riffer::Deprecation.warn(id: :evals, message: Riffer::Evals::DEPRECATION_MESSAGE)
10
11
  validate_agent!(agent)
11
12
  validate_evaluators!(evaluators)
12
13
 
@@ -13,8 +13,8 @@ class Riffer::Evals::Judge
13
13
  description "Submit your evaluation score and reasoning"
14
14
 
15
15
  params do
16
- required :score, Float, description: "Evaluation score between 0.0 and 1.0"
17
- required :reason, String, description: "Brief explanation for the score"
16
+ required :score, :number, description: "Evaluation score between 0.0 and 1.0"
17
+ required :reason, :string, description: "Brief explanation for the score"
18
18
  end
19
19
 
20
20
  #--
data/lib/riffer/evals.rb CHANGED
@@ -2,4 +2,6 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module Riffer::Evals
5
+ DEPRECATION_MESSAGE = "Riffer::Evals is deprecated and will move out of riffer into the riffer-evals gem " \
6
+ "(see docs/EVALS.md)." #: String
5
7
  end
@@ -19,7 +19,7 @@ class Riffer::Mcp::SearchTool < Riffer::Tool
19
19
  description "Search for available MCP tools by name or description."
20
20
 
21
21
  params do
22
- required :query, String, description: "Non-empty substring to filter tools by name or description."
22
+ required :query, :string, description: "Non-empty substring to filter tools by name or description."
23
23
  end
24
24
 
25
25
  #--
data/lib/riffer/mcp.rb CHANGED
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
  # rbs_inline: enabled
3
3
 
4
+ # @deprecated MCP client support will be removed; wrap the +mcp+ gem in your own Riffer::Tool (see docs/MCP.md).
4
5
  module Riffer::Mcp
5
6
  extend self
6
7
 
@@ -14,6 +15,12 @@ module Riffer::Mcp
14
15
  #--
15
16
  #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
16
17
  def register(manifest_or_hash)
18
+ Riffer::Deprecation.warn(
19
+ id: :mcp_register,
20
+ message: "Riffer::Mcp.register is deprecated; MCP client support will be removed in a future release. " \
21
+ "Wrap the mcp gem in your own Riffer::Tool instead (see docs/MCP.md).",
22
+ )
23
+
17
24
  Registry.register(manifest_or_hash)
18
25
  end
19
26
 
@@ -14,6 +14,7 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
14
14
  name: msg[:name],
15
15
  error: msg[:error],
16
16
  error_type: msg[:error_type]&.to_sym,
17
+ loaded_tools: msg[:loaded_tools] || [],
17
18
  )
18
19
  end
19
20
 
@@ -21,15 +22,17 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
21
22
  attr_reader :name #: String # @dynamic name
22
23
  attr_reader :error #: String? # @dynamic error
23
24
  attr_reader :error_type #: Symbol? # @dynamic error_type
25
+ attr_reader :loaded_tools #: Array[String] # @dynamic loaded_tools
24
26
 
25
27
  #--
26
- #: (String, tool_call_id: String, name: String, ?id: String?, ?error: String?, ?error_type: Symbol?) -> void
27
- def initialize(content, tool_call_id:, name:, id: nil, error: nil, error_type: nil)
28
+ #: (String, tool_call_id: String, name: String, ?id: String?, ?error: String?, ?error_type: Symbol?, ?loaded_tools: Array[String]) -> void
29
+ def initialize(content, tool_call_id:, name:, id: nil, error: nil, error_type: nil, loaded_tools: [])
28
30
  super(content, id: id)
29
31
  @tool_call_id = tool_call_id
30
32
  @name = name
31
33
  @error = error
32
34
  @error_type = error_type
35
+ @loaded_tools = loaded_tools
33
36
  end
34
37
 
35
38
  #--
@@ -53,6 +56,7 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
53
56
  hash[:error] = error
54
57
  hash[:error_type] = error_type
55
58
  end
59
+ hash[:loaded_tools] = loaded_tools unless loaded_tools.empty?
56
60
  hash
57
61
  end
58
62
  end
@@ -14,7 +14,7 @@ class Riffer::Params::AnyOf
14
14
  end
15
15
 
16
16
  #--
17
- #: (?Module?, ?description: String?, ?enum: Array[untyped]?, ?format: String?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
17
+ #: (?(Symbol | Module)?, ?description: String?, ?enum: Array[untyped]?, ?format: String?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
18
18
  def variant(type = nil, description: nil, enum: nil, format: nil, &block)
19
19
  if type
20
20
  raise Riffer::ArgumentError, "variant takes a type or a block, not both" if block
@@ -36,15 +36,12 @@ class Riffer::Params::AnyOf
36
36
  private
37
37
 
38
38
  #--
39
- #: (Module, String?, Array[untyped]?, String?) -> Riffer::Params::Param
39
+ #: (Symbol | Module, String?, Array[untyped]?, String?) -> Riffer::Params::Param
40
40
  def primitive(type, description, enum, format)
41
- unless Riffer::Params::Param::PRIMITIVE_TYPES.include?(type)
42
- primitives = Riffer::Params::Param::PRIMITIVE_TYPES.map(&:name).join(", ")
43
- raise Riffer::ArgumentError, "variant type must be a primitive type (#{primitives}), got #{type}"
44
- end
45
-
46
41
  Riffer::Params::Param.new(
47
- name: @name, type: type, required: true, description: description, enum: enum, format: format,
42
+ name: @name, type: Riffer::Params::Param.resolve_type!(type, "variant type", Riffer::Params::Param::PRIMITIVE_TYPES),
43
+ required: true,
44
+ description: description, enum: enum, format: format,
48
45
  )
49
46
  end
50
47
  end
@@ -1,6 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
  # rbs_inline: enabled
3
3
 
4
- # Ruby has no +Boolean+ class, so params declare booleans with this sentinel.
4
+ # Deprecated: declare boolean params with +:boolean+.
5
5
  module Riffer::Params::Boolean
6
6
  end