riffer 0.55.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 (57) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +18 -0
  4. data/README.md +2 -1
  5. data/UPGRADING.md +3 -0
  6. data/docs/AGENT_LIFECYCLE.md +1 -1
  7. data/docs/CONFIGURATION.md +48 -1
  8. data/docs/GUARDRAILS.md +2 -0
  9. data/docs/MESSAGES.md +112 -15
  10. data/docs/STABILITY.md +32 -0
  11. data/docs/STREAM_EVENTS.md +16 -0
  12. data/docs/TESTING.md +22 -1
  13. data/docs/providers/AMAZON_BEDROCK.md +1 -1
  14. data/docs/providers/ANTHROPIC.md +18 -14
  15. data/docs/providers/CUSTOM_PROVIDERS.md +24 -0
  16. data/docs/providers/GEMINI.md +1 -1
  17. data/docs/providers/GOOGLE_CLOUD.md +1 -1
  18. data/docs/providers/MOCK_PROVIDER.md +2 -0
  19. data/docs/providers/OPENAI.md +3 -1
  20. data/docs-site/manifest.yml +3 -0
  21. data/lib/riffer/agent/run.rb +28 -13
  22. data/lib/riffer/agent/session.rb +33 -10
  23. data/lib/riffer/config/future.rb +53 -0
  24. data/lib/riffer/config/pricing.rb +5 -15
  25. data/lib/riffer/config.rb +16 -0
  26. data/lib/riffer/deprecation/event.rb +25 -0
  27. data/lib/riffer/deprecation.rb +60 -0
  28. data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
  29. data/lib/riffer/messages/assistant/text_part.rb +52 -0
  30. data/lib/riffer/messages/assistant.rb +64 -17
  31. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +25 -1
  32. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +51 -29
  33. data/lib/riffer/providers/base.rb +15 -6
  34. data/lib/riffer/providers/open_ai.rb +21 -16
  35. data/lib/riffer/stream_events/server_tool_done.rb +21 -0
  36. data/lib/riffer/testing.rb +6 -0
  37. data/lib/riffer/version.rb +1 -1
  38. data/lib/riffer.rb +2 -0
  39. data/sig/generated/riffer/agent/run.rbs +5 -0
  40. data/sig/generated/riffer/agent/session.rbs +6 -0
  41. data/sig/generated/riffer/config/future.rbs +29 -0
  42. data/sig/generated/riffer/config/pricing.rbs +0 -9
  43. data/sig/generated/riffer/config.rbs +8 -0
  44. data/sig/generated/riffer/deprecation/event.rbs +17 -0
  45. data/sig/generated/riffer/deprecation.rbs +27 -0
  46. data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
  47. data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
  48. data/sig/generated/riffer/messages/assistant.rbs +24 -11
  49. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +10 -0
  50. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +18 -9
  51. data/sig/generated/riffer/providers/base.rbs +5 -0
  52. data/sig/generated/riffer/providers/open_ai.rbs +7 -2
  53. data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
  54. data/sig/generated/riffer/testing.rbs +4 -0
  55. data/sig/generated/riffer.rbs +3 -0
  56. data/sig/manual/riffer/deprecation.rbs +5 -0
  57. metadata +16 -1
@@ -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
@@ -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,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
@@ -45,6 +45,8 @@ class Riffer::Config
45
45
 
46
46
  attr_reader :files #: Riffer::Config::Files # @dynamic files
47
47
 
48
+ attr_reader :future #: Riffer::Config::Future # @dynamic future
49
+
48
50
  # @deprecated Use +catalog_files+.
49
51
  attr_reader :pricing #: Riffer::Config::Pricing # @dynamic pricing
50
52
 
@@ -86,6 +88,18 @@ class Riffer::Config
86
88
  @message_id_strategy = value
87
89
  end
88
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
+
89
103
  #--
90
104
  #: () -> void
91
105
  def initialize
@@ -102,9 +116,11 @@ class Riffer::Config
102
116
  @skills = Skills.new
103
117
  @tracing = Tracing.new
104
118
  @files = Files.new
119
+ @future = Future.new
105
120
  @pricing = Pricing.new
106
121
  no_files = [] #: Array[String]
107
122
  @catalog_files = no_files.freeze
108
123
  @message_id_strategy = :none
124
+ @deprecations = :warn
109
125
  end
110
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,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
@@ -10,6 +10,12 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
10
10
  # @rbs @web_search_query: String?
11
11
  # @rbs @completed: bool
12
12
 
13
+ # Each server tool has its own result type (web search run from code execution returns
14
+ # +code_execution_tool_result+ blocks too), and the API rejects a server_tool_use sent back
15
+ # without its result. +mcp_tool_result+ pairs with +mcp_tool_use+, which riffer drops, so
16
+ # its result is dropped too.
17
+ SERVER_TOOL_RESULT_TYPE = /\A(?!mcp_)\w+_tool_result\z/ #: Regexp
18
+
13
19
  #--
14
20
  #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
15
21
  def self.reasoning_part(block)
@@ -28,6 +34,20 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
28
34
  end
29
35
  end
30
36
 
37
+ #--
38
+ #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ServerToolPart
39
+ def self.server_tool_part(block)
40
+ call = block[:type] == "server_tool_use"
41
+
42
+ Riffer::Messages::Assistant::ServerToolPart.new(
43
+ name: call ? block[:name] : block[:type].delete_suffix("_tool_result"),
44
+ kind: call ? :call : :result,
45
+ data: JSON.generate(block),
46
+ id: call ? block[:id] : block[:tool_use_id],
47
+ format: Riffer::Providers::AnthropicCompatible::MessagesAPI::REASONING_FORMAT,
48
+ )
49
+ end
50
+
31
51
  #--
32
52
  #: (tools: Array[singleton(Riffer::Tool)]) -> void
33
53
  def initialize(tools:)
@@ -137,11 +157,15 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
137
157
  yielder << Riffer::StreamEvents::ReasoningDone.new(part)
138
158
  when "server_tool_use"
139
159
  block[:input] = parse_input(@partial_json.delete(index).to_s) || {}
160
+ yielder << Riffer::StreamEvents::ServerToolDone.new(self.class.server_tool_part(block))
140
161
  return unless block[:name] == "web_search"
141
162
 
142
163
  @web_search_query = block[:input]["query"]
143
164
  yielder << Riffer::StreamEvents::WebSearchStatus.new("searching", query: @web_search_query)
144
- when "web_search_tool_result"
165
+ when SERVER_TOOL_RESULT_TYPE
166
+ yielder << Riffer::StreamEvents::ServerToolDone.new(self.class.server_tool_part(block))
167
+ return unless block[:type] == "web_search_tool_result"
168
+
145
169
  yielder << Riffer::StreamEvents::WebSearchDone.new(@web_search_query || "", sources: web_search_sources(block))
146
170
  @web_search_query = nil
147
171
  end