riffer 0.55.0 → 0.57.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +37 -0
  4. data/README.md +3 -2
  5. data/UPGRADING.md +3 -0
  6. data/docs/AGENTS.md +105 -50
  7. data/docs/AGENT_LIFECYCLE.md +2 -2
  8. data/docs/CONFIGURATION.md +54 -3
  9. data/docs/EVALS.md +2 -0
  10. data/docs/GUARDRAILS.md +2 -0
  11. data/docs/MCP.md +36 -0
  12. data/docs/MESSAGES.md +125 -15
  13. data/docs/OVERVIEW.md +7 -7
  14. data/docs/SERIALIZATION.md +12 -2
  15. data/docs/SKILLS.md +1 -1
  16. data/docs/STABILITY.md +32 -0
  17. data/docs/STREAM_EVENTS.md +16 -0
  18. data/docs/TESTING.md +22 -1
  19. data/docs/TOOLS.md +93 -37
  20. data/docs/TOOL_ADVANCED.md +7 -0
  21. data/docs/providers/AMAZON_BEDROCK.md +7 -3
  22. data/docs/providers/ANTHROPIC.md +53 -16
  23. data/docs/providers/AZURE_OPENAI.md +9 -3
  24. data/docs/providers/CUSTOM_PROVIDERS.md +43 -0
  25. data/docs/providers/GEMINI.md +9 -5
  26. data/docs/providers/GOOGLE_CLOUD.md +10 -5
  27. data/docs/providers/MOCK_PROVIDER.md +4 -0
  28. data/docs/providers/OPENAI.md +28 -4
  29. data/docs/providers/OPENROUTER.md +11 -3
  30. data/docs/providers/PROVIDERS.md +1 -1
  31. data/docs-site/index.html.erb +1 -1
  32. data/docs-site/manifest.yml +3 -0
  33. data/lib/riffer/agent/config.rb +21 -0
  34. data/lib/riffer/agent/context.rb +36 -18
  35. data/lib/riffer/agent/run.rb +82 -21
  36. data/lib/riffer/agent/serializer.rb +5 -0
  37. data/lib/riffer/agent/session.rb +34 -10
  38. data/lib/riffer/agent.rb +43 -0
  39. data/lib/riffer/config/future.rb +53 -0
  40. data/lib/riffer/config/mcp.rb +17 -0
  41. data/lib/riffer/config/pricing.rb +5 -15
  42. data/lib/riffer/config.rb +28 -1
  43. data/lib/riffer/deprecation/event.rb +25 -0
  44. data/lib/riffer/deprecation.rb +60 -0
  45. data/lib/riffer/evals/evaluator.rb +8 -1
  46. data/lib/riffer/evals/evaluator_runner.rb +1 -0
  47. data/lib/riffer/evals/judge.rb +2 -2
  48. data/lib/riffer/evals.rb +2 -0
  49. data/lib/riffer/mcp/search_tool.rb +1 -1
  50. data/lib/riffer/mcp.rb +7 -0
  51. data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
  52. data/lib/riffer/messages/assistant/text_part.rb +52 -0
  53. data/lib/riffer/messages/assistant.rb +64 -17
  54. data/lib/riffer/messages/tool.rb +6 -2
  55. data/lib/riffer/params/any_of.rb +5 -8
  56. data/lib/riffer/params/boolean.rb +1 -1
  57. data/lib/riffer/params/param.rb +96 -67
  58. data/lib/riffer/params.rb +50 -71
  59. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +28 -11
  60. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +136 -38
  61. data/lib/riffer/providers/base.rb +57 -12
  62. data/lib/riffer/providers/deferred_tool_gateway/sink.rb +54 -0
  63. data/lib/riffer/providers/deferred_tool_gateway/tool.rb +17 -0
  64. data/lib/riffer/providers/deferred_tool_gateway.rb +150 -0
  65. data/lib/riffer/providers/gemini.rb +5 -5
  66. data/lib/riffer/providers/mock.rb +6 -0
  67. data/lib/riffer/providers/open_ai.rb +59 -26
  68. data/lib/riffer/skills/activate_tool.rb +1 -1
  69. data/lib/riffer/stream_events/server_tool_done.rb +21 -0
  70. data/lib/riffer/testing.rb +6 -0
  71. data/lib/riffer/tool.rb +92 -2
  72. data/lib/riffer/tools/response.rb +11 -2
  73. data/lib/riffer/version.rb +1 -1
  74. data/lib/riffer.rb +2 -0
  75. data/sig/generated/riffer/agent/config.rbs +13 -1
  76. data/sig/generated/riffer/agent/context.rbs +16 -0
  77. data/sig/generated/riffer/agent/run.rbs +19 -2
  78. data/sig/generated/riffer/agent/session.rbs +6 -0
  79. data/sig/generated/riffer/agent.rbs +13 -0
  80. data/sig/generated/riffer/config/future.rbs +29 -0
  81. data/sig/generated/riffer/config/mcp.rbs +7 -0
  82. data/sig/generated/riffer/config/pricing.rbs +0 -9
  83. data/sig/generated/riffer/config.rbs +13 -1
  84. data/sig/generated/riffer/deprecation/event.rbs +17 -0
  85. data/sig/generated/riffer/deprecation.rbs +27 -0
  86. data/sig/generated/riffer/evals/evaluator.rbs +4 -0
  87. data/sig/generated/riffer/evals.rbs +1 -0
  88. data/sig/generated/riffer/mcp.rbs +1 -0
  89. data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
  90. data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
  91. data/sig/generated/riffer/messages/assistant.rbs +24 -11
  92. data/sig/generated/riffer/messages/tool.rbs +4 -2
  93. data/sig/generated/riffer/params/any_of.rbs +4 -4
  94. data/sig/generated/riffer/params/boolean.rbs +1 -1
  95. data/sig/generated/riffer/params/param.rbs +28 -14
  96. data/sig/generated/riffer/params.rbs +20 -20
  97. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +12 -5
  98. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +50 -9
  99. data/sig/generated/riffer/providers/base.rbs +18 -0
  100. data/sig/generated/riffer/providers/deferred_tool_gateway/sink.rbs +23 -0
  101. data/sig/generated/riffer/providers/deferred_tool_gateway/tool.rbs +4 -0
  102. data/sig/generated/riffer/providers/deferred_tool_gateway.rbs +58 -0
  103. data/sig/generated/riffer/providers/mock.rbs +4 -0
  104. data/sig/generated/riffer/providers/open_ai.rbs +23 -6
  105. data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
  106. data/sig/generated/riffer/testing.rbs +4 -0
  107. data/sig/generated/riffer/tool.rbs +48 -2
  108. data/sig/generated/riffer/tools/response.rbs +9 -2
  109. data/sig/generated/riffer.rbs +3 -0
  110. data/sig/manual/riffer/deprecation.rbs +5 -0
  111. data/sig/manual/riffer/providers/deferred_tool_gateway.rbs +5 -0
  112. metadata +23 -3
  113. data/lib/riffer/tools/toolable.rb +0 -113
  114. data/sig/generated/riffer/tools/toolable.rbs +0 -66
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
 
@@ -0,0 +1,73 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ # A call or result of a tool the provider ran itself (e.g. web search). Stored and replayed
5
+ # verbatim under the same rule as reasoning parts: only the adapter whose +format+ it is sends
6
+ # it back.
7
+ class Riffer::Messages::Assistant::ServerToolPart
8
+ KINDS = %i[call result].freeze #: Array[Symbol]
9
+
10
+ attr_reader :name #: String # @dynamic name
11
+ attr_reader :kind #: Symbol # @dynamic kind
12
+
13
+ # The provider's block, JSON-encoded and unchanged.
14
+ attr_reader :data #: String # @dynamic data
15
+
16
+ # Shared by a call and its result.
17
+ attr_reader :id #: String? # @dynamic id
18
+
19
+ attr_reader :format #: String? # @dynamic format
20
+
21
+ #--
22
+ #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ServerToolPart)) -> Riffer::Messages::Assistant::ServerToolPart
23
+ def self.from_hash(part)
24
+ return part if part.is_a?(Riffer::Messages::Assistant::ServerToolPart)
25
+
26
+ new(
27
+ name: part[:name],
28
+ kind: part[:kind].to_sym,
29
+ data: part[:data],
30
+ id: part[:id],
31
+ format: part[:format],
32
+ )
33
+ end
34
+
35
+ #--
36
+ #: (name: String, kind: Symbol, data: String, ?id: String?, ?format: String?) -> void
37
+ def initialize(name:, kind:, data:, id: nil, format: nil)
38
+ unless KINDS.include?(kind)
39
+ raise Riffer::ArgumentError,
40
+ "kind must be one of #{KINDS.inspect}, got #{kind.inspect}"
41
+ end
42
+
43
+ @name = name
44
+ @kind = kind
45
+ @data = data
46
+ @id = id
47
+ @format = format
48
+ end
49
+
50
+ #--
51
+ #: () -> Hash[Symbol, untyped]
52
+ def to_h
53
+ { name: name, kind: kind, data: data, id: id, format: format }.compact
54
+ end
55
+
56
+ #--
57
+ #: (untyped) -> bool
58
+ def ==(other)
59
+ other.is_a?(Riffer::Messages::Assistant::ServerToolPart) && to_h == other.to_h
60
+ end
61
+
62
+ #--
63
+ #: (untyped) -> bool
64
+ def eql?(other)
65
+ self == other
66
+ end
67
+
68
+ #--
69
+ #: () -> Integer
70
+ def hash
71
+ to_h.hash
72
+ end
73
+ end
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Messages::Assistant::TextPart
5
+ attr_reader :text #: String # @dynamic text
6
+
7
+ # The provider's whole block as JSON, kept when it carries more than the text (e.g. Anthropic
8
+ # +citations+), so the adapter that produced it can send it back unchanged.
9
+ attr_reader :data #: String? # @dynamic data
10
+
11
+ attr_reader :format #: String? # @dynamic format
12
+
13
+ #--
14
+ #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::TextPart)) -> Riffer::Messages::Assistant::TextPart
15
+ def self.from_hash(part)
16
+ return part if part.is_a?(Riffer::Messages::Assistant::TextPart)
17
+
18
+ new(part[:text].to_s, data: part[:data], format: part[:format])
19
+ end
20
+
21
+ #--
22
+ #: (String, ?data: String?, ?format: String?) -> void
23
+ def initialize(text, data: nil, format: nil)
24
+ @text = text
25
+ @data = data
26
+ @format = format
27
+ end
28
+
29
+ #--
30
+ #: () -> Hash[Symbol, untyped]
31
+ def to_h
32
+ { text: text, data: data, format: format }.compact
33
+ end
34
+
35
+ #--
36
+ #: (untyped) -> bool
37
+ def ==(other)
38
+ other.is_a?(Riffer::Messages::Assistant::TextPart) && to_h == other.to_h
39
+ end
40
+
41
+ #--
42
+ #: (untyped) -> bool
43
+ def eql?(other)
44
+ self == other
45
+ end
46
+
47
+ #--
48
+ #: () -> Integer
49
+ def hash
50
+ to_h.hash
51
+ end
52
+ end
@@ -5,6 +5,13 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
5
5
  # The other reasoning part types carry no prose.
6
6
  REASONING_TEXT_TYPES = %i[text summary].freeze #: Array[Symbol]
7
7
 
8
+ PART_TAGS = {
9
+ Riffer::Messages::Assistant::TextPart => :text,
10
+ Riffer::Messages::Assistant::ReasoningPart => :reasoning,
11
+ Riffer::Messages::Assistant::ToolCall => :tool_call,
12
+ Riffer::Messages::Assistant::ServerToolPart => :server_tool,
13
+ }.freeze #: Hash[singleton(Riffer::Messages::Assistant::TextPart) | singleton(Riffer::Messages::Assistant::ReasoningPart) | singleton(Riffer::Messages::Assistant::ToolCall) | singleton(Riffer::Messages::Assistant::ServerToolPart), Symbol]
14
+
8
15
  #--
9
16
  #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant)) -> Riffer::Messages::Assistant
10
17
  def self.from_hash(msg)
@@ -13,6 +20,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
13
20
  new(
14
21
  msg[:content],
15
22
  id: msg[:id],
23
+ parts: msg[:parts]&.map { |part| part_from_hash(part) },
16
24
  tool_calls: (msg[:tool_calls] || []).map { |tc| Riffer::Messages::Assistant::ToolCall.from_hash(tc) },
17
25
  reasoning: (msg[:reasoning] || []).map { |part| Riffer::Messages::Assistant::ReasoningPart.from_hash(part) },
18
26
  token_usage: msg[:token_usage] && Riffer::Providers::TokenUsage.from_hash(msg[:token_usage]),
@@ -22,6 +30,24 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
22
30
  )
23
31
  end
24
32
 
33
+ #--
34
+ #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart)) -> (Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart)
35
+ def self.part_from_hash(part)
36
+ return part unless part.is_a?(Hash)
37
+
38
+ klass = PART_TAGS.key(part[:part]&.to_sym)
39
+ unless klass
40
+ raise Riffer::ArgumentError, "part must be one of #{PART_TAGS.values.inspect}, got #{part[:part].inspect}"
41
+ end
42
+
43
+ klass.from_hash(part.except(:part))
44
+ end
45
+ private_class_method :part_from_hash
46
+
47
+ # The turn in the order the provider produced it. +content+, +tool_calls+ and +reasoning+ are
48
+ # views over it.
49
+ attr_reader :parts #: Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart] # @dynamic parts
50
+
25
51
  attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
26
52
 
27
53
  attr_reader :reasoning #: Array[Riffer::Messages::Assistant::ReasoningPart] # @dynamic reasoning
@@ -34,20 +60,14 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
34
60
 
35
61
  attr_reader :finish_reason_raw #: String? # @dynamic finish_reason_raw
36
62
 
63
+ # Without +parts:+, the parts are built in a fixed order: reasoning, then the content as one
64
+ # text part, then tool calls.
37
65
  #--
38
- #: (
39
- # String,
40
- # ?id: String?,
41
- # ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall],
42
- # ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
43
- # ?token_usage: Riffer::Providers::TokenUsage?,
44
- # ?structured_output: Hash[Symbol, untyped]?,
45
- # ?finish_reason: Symbol?,
46
- # ?finish_reason_raw: String?
47
- # ) -> void
66
+ #: (?String?, ?id: String?, ?parts: Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?, ?finish_reason_raw: String?) -> void
48
67
  def initialize(
49
- content,
68
+ content = nil,
50
69
  id: nil,
70
+ parts: nil,
51
71
  tool_calls: [],
52
72
  reasoning: [],
53
73
  token_usage: nil,
@@ -60,9 +80,14 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
60
80
  raise Riffer::ArgumentError, "finish_reason must be one of #{values}, got #{finish_reason.inspect}"
61
81
  end
62
82
 
63
- super(content, id: id)
64
- @tool_calls = tool_calls
65
- @reasoning = reasoning
83
+ if parts && (content || !tool_calls.empty? || !reasoning.empty?)
84
+ raise Riffer::ArgumentError, "pass either parts: or content, tool_calls: and reasoning:, not both"
85
+ end
86
+
87
+ @parts = parts || default_parts(content, tool_calls, reasoning)
88
+ super(@parts.filter_map { |part| part.text if part.is_a?(Riffer::Messages::Assistant::TextPart) }.join, id: id)
89
+ @tool_calls = @parts.grep(Riffer::Messages::Assistant::ToolCall) #: Array[Riffer::Messages::Assistant::ToolCall]
90
+ @reasoning = @parts.grep(Riffer::Messages::Assistant::ReasoningPart) #: Array[Riffer::Messages::Assistant::ReasoningPart]
66
91
  @token_usage = token_usage
67
92
  @structured_output = structured_output
68
93
  @finish_reason = finish_reason
@@ -103,6 +128,12 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
103
128
  #--
104
129
  #: (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
105
130
  def +(other)
131
+ unless [self, other].all? { |message| described_by_fields?(message) }
132
+ merged = parts.dup
133
+ merged << Riffer::Messages::Assistant::TextPart.new("\n\n") unless content.empty? || other.content.empty?
134
+ return self.class.new(parts: merged.concat(other.parts))
135
+ end
136
+
106
137
  self.class.new(
107
138
  "#{content}\n\n#{other.content}",
108
139
  tool_calls: tool_calls + other.tool_calls,
@@ -113,14 +144,30 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
113
144
  #--
114
145
  #: () -> Hash[Symbol, untyped]
115
146
  def to_h
116
- hash = { role: role, content: content } #: Hash[Symbol, untyped]
147
+ hash = { role: role } #: Hash[Symbol, untyped]
117
148
  hash[:id] = id if id
118
- hash[:tool_calls] = tool_calls.map(&:to_h) unless tool_calls.empty?
119
- hash[:reasoning] = reasoning.map(&:to_h) if reasoning?
149
+ hash[:parts] = parts.map { |part| { part: PART_TAGS.fetch(part.class), **part.to_h } }
120
150
  hash[:token_usage] = token_usage.to_h if token_usage
121
151
  hash[:structured_output] = structured_output if structured_output?
122
152
  hash[:finish_reason] = finish_reason if finish_reason
123
153
  hash[:finish_reason_raw] = finish_reason_raw if finish_reason_raw
124
154
  hash
125
155
  end
156
+
157
+ private
158
+
159
+ #--
160
+ #: (String?, Array[Riffer::Messages::Assistant::ToolCall], Array[Riffer::Messages::Assistant::ReasoningPart]) -> Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
161
+ def default_parts(content, tool_calls, reasoning)
162
+ parts = [] #: Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
163
+ parts.concat(reasoning)
164
+ parts << Riffer::Messages::Assistant::TextPart.new(content) unless content.nil? || content.empty?
165
+ parts.concat(tool_calls)
166
+ end
167
+
168
+ #--
169
+ #: (Riffer::Messages::Assistant) -> bool
170
+ def described_by_fields?(message)
171
+ message.parts == default_parts(message.content, message.tool_calls, message.reasoning)
172
+ end
126
173
  end
@@ -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
@@ -4,31 +4,27 @@
4
4
  require "json"
5
5
 
6
6
  class Riffer::Params::Param
7
- TYPE_MAPPINGS = {
8
- String => "string",
9
- Integer => "integer",
10
- Float => "number",
11
- Riffer::Params::Boolean => "boolean",
12
- TrueClass => "boolean",
13
- FalseClass => "boolean",
14
- Array => "array",
15
- Hash => "object",
16
- }.freeze #: Hash[Module, String]
17
-
18
- PRIMITIVE_TYPES = (TYPE_MAPPINGS.keys - [Array, Hash]).freeze #: Array[Module]
19
-
20
- JSON_TYPE_MAPPINGS = {
21
- "string" => String,
22
- "integer" => Integer,
23
- "number" => Float,
24
- "boolean" => Riffer::Params::Boolean,
25
- "array" => Array,
26
- "object" => Hash,
27
- }.freeze #: Hash[String, Module]
7
+ PRIMITIVE_TYPES = %i[string integer number boolean].freeze #: Array[Symbol]
8
+
9
+ TYPES = [*PRIMITIVE_TYPES, :array, :object, :any_of].freeze #: Array[Symbol]
10
+
11
+ CLASS_TYPES = {
12
+ String => :string,
13
+ Integer => :integer,
14
+ Float => :number,
15
+ Riffer::Params::Boolean => :boolean,
16
+ TrueClass => :boolean,
17
+ FalseClass => :boolean,
18
+ Array => :array,
19
+ Hash => :object,
20
+ Riffer::Params::AnyOf => :any_of,
21
+ }.freeze #: Hash[Module, Symbol]
22
+
23
+ JSON_TYPE_MAPPINGS = (TYPES - [:any_of]).to_h { |type| [type.name, type] }.freeze #: Hash[String, Symbol]
28
24
 
29
25
  attr_reader :name #: Symbol # @dynamic name
30
26
 
31
- attr_reader :type #: Module # @dynamic type
27
+ attr_reader :type #: Symbol # @dynamic type
32
28
 
33
29
  attr_reader :required #: bool # @dynamic required
34
30
 
@@ -40,7 +36,7 @@ class Riffer::Params::Param
40
36
 
41
37
  attr_reader :default #: untyped # @dynamic default
42
38
 
43
- attr_reader :item_type #: Module? # @dynamic item_type
39
+ attr_reader :item_type #: Symbol? # @dynamic item_type
44
40
 
45
41
  attr_reader :dimensions #: Integer # @dynamic dimensions
46
42
 
@@ -48,17 +44,56 @@ class Riffer::Params::Param
48
44
 
49
45
  attr_reader :variants #: Array[Riffer::Params | Riffer::Params::Param]? # @dynamic variants
50
46
 
47
+ #--
48
+ #: (untyped) -> Symbol?
49
+ def self.resolve_type(type)
50
+ return type if TYPES.include?(type)
51
+
52
+ symbol = CLASS_TYPES[type] #: Symbol?
53
+ return unless symbol
54
+
55
+ Riffer::Deprecation.warn(
56
+ id: :param_class_types,
57
+ message: "#{type.name} as a param type is deprecated and will be removed in a future version, " \
58
+ "not before 1 December 2026; use #{symbol.inspect}.",
59
+ )
60
+ symbol
61
+ end
62
+
63
+ #--
64
+ #: (untyped, String, Array[Symbol]) -> Symbol
65
+ def self.resolve_type!(type, subject, allowed)
66
+ resolved = resolve_type(type)
67
+ return resolved if resolved && allowed.include?(resolved)
68
+
69
+ raise Riffer::ArgumentError, "#{subject} must be one of #{allowed.map(&:inspect).join(', ')}, got #{type.inspect}"
70
+ end
71
+
72
+ #--
73
+ #: (Symbol, untyped) -> bool
74
+ def self.value_of_type?(type, value)
75
+ case type
76
+ when :string then value.is_a?(String)
77
+ when :integer then value.is_a?(Integer)
78
+ when :number then value.is_a?(Numeric)
79
+ when :boolean then [true, false].include?(value)
80
+ when :array then value.is_a?(Array)
81
+ when :object then value.is_a?(Hash)
82
+ else false
83
+ end
84
+ end
85
+
51
86
  #--
52
87
  #: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
53
88
  def self.from_json_schema(name, schema, required:)
54
89
  variants = resolve_variants(name, schema[:anyOf]) if schema.key?(:anyOf)
55
- ruby_type = variants ? Riffer::Params::AnyOf : json_type_to_ruby(schema[:type])
56
- nested = resolve_nested_params(ruby_type, schema)
57
- item_type, dimensions, items = resolve_typed_items(schema) if ruby_type == Array && !nested
90
+ type = variants ? :any_of : json_type(schema[:type])
91
+ nested = resolve_nested_params(type, schema)
92
+ item_type, dimensions, items = resolve_typed_items(schema) if type == :array && !nested
58
93
 
59
94
  new(
60
95
  name: name,
61
- type: ruby_type,
96
+ type: type,
62
97
  required: required,
63
98
  description: schema[:description],
64
99
  enum: schema[:enum] || items&.dig(:enum),
@@ -91,18 +126,18 @@ class Riffer::Params::Param
91
126
  private_class_method :resolve_variants
92
127
 
93
128
  #--
94
- #: (Module, Hash[Symbol, untyped]) -> Riffer::Params?
95
- def self.resolve_nested_params(ruby_type, schema)
96
- if ruby_type == Hash && schema[:properties]
129
+ #: (Symbol, Hash[Symbol, untyped]) -> Riffer::Params?
130
+ def self.resolve_nested_params(type, schema)
131
+ if type == :object && schema[:properties]
97
132
  Riffer::Params.from_json_schema(schema)
98
- elsif ruby_type == Array && schema[:items].is_a?(Hash) && schema[:items][:properties]
133
+ elsif type == :array && schema[:items].is_a?(Hash) && schema[:items][:properties]
99
134
  Riffer::Params.from_json_schema(schema[:items])
100
135
  end
101
136
  end
102
137
  private_class_method :resolve_nested_params
103
138
 
104
139
  #--
105
- #: (Hash[Symbol, untyped]) -> [Module, Integer, Hash[Symbol, untyped]]?
140
+ #: (Hash[Symbol, untyped]) -> [Symbol, Integer, Hash[Symbol, untyped]]?
106
141
  def self.resolve_typed_items(schema)
107
142
  items = schema[:items]
108
143
  return unless items.is_a?(Hash)
@@ -110,7 +145,7 @@ class Riffer::Params::Param
110
145
  dimensions = 1
111
146
  # Riffer only writes nested arrays with enum/format and a single primitive type on the innermost
112
147
  # items, and no nullable inner arrays; any other shape would read back with a different meaning.
113
- while json_type_to_ruby(items[:type]) == Array
148
+ while json_type(items[:type]) == :array
114
149
  inner = items[:items]
115
150
  unless items[:type] == "array" && inner.is_a?(Hash) && !items.keys.intersect?(%i[enum format])
116
151
  raise Riffer::ArgumentError, "Unsupported nested array: #{items.to_json}"
@@ -120,7 +155,7 @@ class Riffer::Params::Param
120
155
  dimensions += 1
121
156
  end
122
157
 
123
- item_type = json_type_to_ruby(items[:type])
158
+ item_type = json_type(items[:type])
124
159
  if dimensions > 1
125
160
  if schema.keys.intersect?(%i[enum format])
126
161
  raise Riffer::ArgumentError, "Unsupported nested array: #{schema.to_json}"
@@ -135,21 +170,19 @@ class Riffer::Params::Param
135
170
  private_class_method :resolve_typed_items
136
171
 
137
172
  #--
138
- #: (untyped) -> Module
139
- def self.json_type_to_ruby(type)
173
+ #: (untyped) -> Symbol
174
+ def self.json_type(type)
140
175
  types = Array(type) - ["null"]
141
- ruby_type = JSON_TYPE_MAPPINGS[types.first] if types.one?
142
- ruby_type || raise(Riffer::ArgumentError, "Unsupported JSON Schema type: #{type.inspect}")
176
+ symbol = JSON_TYPE_MAPPINGS[types.first] if types.one?
177
+ symbol || raise(Riffer::ArgumentError, "Unsupported JSON Schema type: #{type.inspect}")
143
178
  end
144
- private_class_method :json_type_to_ruby
179
+ private_class_method :json_type
145
180
 
146
181
  #--
147
- #: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?item_type: Module?, ?dimensions: Integer, ?nested_params: Riffer::Params?, ?variants: Array[Riffer::Params | Riffer::Params::Param]?) -> void
182
+ #: (name: Symbol, type: Symbol, required: bool, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?item_type: Symbol?, ?dimensions: Integer, ?nested_params: Riffer::Params?, ?variants: Array[Riffer::Params | Riffer::Params::Param]?) -> void
148
183
  def initialize(name:, type:, required:, description: nil, enum: nil, format: nil, default: nil, item_type: nil,
149
184
  dimensions: 1, nested_params: nil, variants: nil)
150
- if type == Riffer::Params::AnyOf && variants.nil?
151
- raise Riffer::ArgumentError, "#{name}: an AnyOf param requires variants"
152
- end
185
+ raise Riffer::ArgumentError, "#{name}: an :any_of param requires variants" if type == :any_of && variants.nil?
153
186
 
154
187
  @name = name.to_sym
155
188
  @type = type
@@ -173,26 +206,22 @@ class Riffer::Params::Param
173
206
  def valid_type?(value)
174
207
  return true if value.nil? && !required
175
208
 
176
- if [Riffer::Params::Boolean, TrueClass, FalseClass].include?(type)
177
- [true, false].include?(value)
178
- elsif type == Float
179
- value.is_a?(Numeric)
180
- elsif type == Riffer::Params::AnyOf
209
+ if type == :any_of
181
210
  Array(variants).any? { |variant| variant.is_a?(Riffer::Params) ? value.is_a?(Hash) : variant.valid_type?(value) }
182
211
  else
183
- value.is_a?(type)
212
+ self.class.value_of_type?(type, value)
184
213
  end
185
214
  end
186
215
 
187
216
  #--
188
217
  #: () -> String
189
218
  def type_name
190
- if type == Riffer::Params::AnyOf
219
+ if type == :any_of
191
220
  names = Array(variants).map { |variant| variant.is_a?(Riffer::Params) ? "object" : variant.type_name }
192
221
  return names.uniq.join(" or ")
193
222
  end
194
223
 
195
- TYPE_MAPPINGS[type] || type.to_s.downcase
224
+ type.name
196
225
  end
197
226
 
198
227
  #--
@@ -202,7 +231,7 @@ class Riffer::Params::Param
202
231
  # Nullable so strict providers can distinguish absent from present.
203
232
  nullable = strict && !required
204
233
 
205
- if type == Riffer::Params::AnyOf && variants
234
+ if type == :any_of && variants
206
235
  schema = { anyOf: variants.map { |variant| variant.to_json_schema(strict: strict) } } #: Hash[Symbol, untyped]
207
236
  schema[:anyOf] << { type: "null" } if nullable
208
237
  schema[:description] = description if description
@@ -233,13 +262,13 @@ class Riffer::Params::Param
233
262
  # source for +from_json_schema+.
234
263
  schema[:default] = default unless strict || default.nil?
235
264
 
236
- if self.type == Array && nested_params
265
+ if self.type == :array && nested_params
237
266
  schema[:items] = nested_params.to_json_schema(strict: strict)
238
- elsif self.type == Array && item_type
239
- items = { type: TYPE_MAPPINGS[item_type], enum: enum, format: format }.compact #: Hash[Symbol, untyped]
267
+ elsif self.type == :array && item_type
268
+ items = { type: item_type.name, enum: enum, format: format }.compact #: Hash[Symbol, untyped]
240
269
  (dimensions - 1).times { items = { type: "array", items: items } }
241
270
  schema[:items] = items
242
- elsif self.type == Hash && nested_params
271
+ elsif self.type == :object && nested_params
243
272
  # The nested schema carries its own type: "object", which would clobber a nullable union.
244
273
  schema.merge!(nested_params.to_json_schema(strict: strict).except(:type))
245
274
  end
@@ -262,16 +291,16 @@ class Riffer::Params::Param
262
291
  @default = Riffer::Helpers::DeepDup.call(source.default)
263
292
  end
264
293
 
265
- # The first matching variant wins, and a Float variant without an enum accepts any number.
294
+ # The first matching variant wins, and a :number variant without an enum accepts any number.
266
295
  #--
267
296
  #: () -> void
268
297
  def validate_variant_order!
269
298
  primitives = Array(variants).grep(Riffer::Params::Param) #: Array[Riffer::Params::Param]
270
- float = primitives.index { |variant| variant.type == Float && variant.enum.nil? }
271
- integer = primitives.rindex { |variant| variant.type == Integer }
272
- return unless float && integer && float < integer
299
+ number = primitives.index { |variant| variant.type == :number && variant.enum.nil? }
300
+ integer = primitives.rindex { |variant| variant.type == :integer }
301
+ return unless number && integer && number < integer
273
302
 
274
- raise Riffer::ArgumentError, "#{name}: an Integer variant after a Float variant without enum: can never match"
303
+ raise Riffer::ArgumentError, "#{name}: an :integer variant after a :number variant without enum: can never match"
275
304
  end
276
305
 
277
306
  #--
@@ -282,8 +311,8 @@ class Riffer::Params::Param
282
311
  "#{name}: format: must be a supported format (#{Riffer::Params::Format::NAMES.join(', ')}), " \
283
312
  "got #{format.inspect}"
284
313
  end
285
- unless type == String || (type == Array && item_type == String)
286
- raise Riffer::ArgumentError, "#{name}: format: requires a String or an Array whose innermost type is String"
314
+ unless type == :string || (type == :array && item_type == :string)
315
+ raise Riffer::ArgumentError, "#{name}: format: requires :string or an :array whose innermost type is :string"
287
316
  end
288
317
  raise Riffer::ArgumentError, "#{name}: format: cannot be used with enum:" if enum
289
318
  end
@@ -292,12 +321,12 @@ class Riffer::Params::Param
292
321
  #: () -> void
293
322
  def validate_strict_shape!
294
323
  # Strict providers reject objects without properties and arrays without items.
295
- if type == Hash && nested_params.nil?
324
+ if type == :object && nested_params.nil?
296
325
  raise Riffer::ArgumentError,
297
- "#{name}: a Hash param requires a block defining its properties under strict schemas"
298
- elsif type == Array && nested_params.nil? && item_type.nil?
326
+ "#{name}: an :object param requires a block defining its properties under strict schemas"
327
+ elsif type == :array && nested_params.nil? && item_type.nil?
299
328
  raise Riffer::ArgumentError,
300
- "#{name}: an Array param requires a block or of: defining its items under strict schemas"
329
+ "#{name}: an :array param requires a block or of: defining its items under strict schemas"
301
330
  end
302
331
  end
303
332
  end