riffer 0.54.0 → 0.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/rules/rbs-inline.md +6 -6
  3. data/.release-please-manifest.json +1 -1
  4. data/.ruby-version +1 -1
  5. data/CHANGELOG.md +46 -0
  6. data/README.md +26 -1
  7. data/Steepfile +2 -2
  8. data/UPGRADING.md +3 -0
  9. data/docs/AGENTS.md +37 -12
  10. data/docs/AGENT_LIFECYCLE.md +1 -1
  11. data/docs/CATALOG.md +8 -8
  12. data/docs/CONFIGURATION.md +95 -17
  13. data/docs/GUARDRAILS.md +2 -0
  14. data/docs/MCP.md +3 -4
  15. data/docs/MESSAGES.md +112 -15
  16. data/docs/STABILITY.md +32 -0
  17. data/docs/STREAM_EVENTS.md +17 -1
  18. data/docs/TESTING.md +22 -1
  19. data/docs/TOOLS.md +11 -11
  20. data/docs/TRACING.md +1 -1
  21. data/docs/providers/AMAZON_BEDROCK.md +3 -1
  22. data/docs/providers/ANTHROPIC.md +44 -44
  23. data/docs/providers/CUSTOM_PROVIDERS.md +59 -0
  24. data/docs/providers/GEMINI.md +76 -26
  25. data/docs/providers/GOOGLE_CLOUD.md +363 -0
  26. data/docs/providers/MOCK_PROVIDER.md +2 -0
  27. data/docs/providers/OPENAI.md +3 -1
  28. data/docs/providers/PROVIDERS.md +30 -18
  29. data/docs-site/manifest.yml +6 -0
  30. data/lib/riffer/agent/run.rb +28 -13
  31. data/lib/riffer/agent/session.rb +33 -10
  32. data/lib/riffer/agent/structured_output.rb +6 -1
  33. data/lib/riffer/config/anthropic.rb +9 -0
  34. data/lib/riffer/config/future.rb +53 -0
  35. data/lib/riffer/config/gemini.rb +9 -0
  36. data/lib/riffer/config/google_cloud.rb +38 -0
  37. data/lib/riffer/config/pricing.rb +5 -15
  38. data/lib/riffer/config.rb +19 -0
  39. data/lib/riffer/deprecation/event.rb +25 -0
  40. data/lib/riffer/deprecation.rb +60 -0
  41. data/lib/riffer/http/client.rb +141 -0
  42. data/lib/riffer/http.rb +5 -0
  43. data/lib/riffer/mcp/client.rb +0 -1
  44. data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
  45. data/lib/riffer/messages/assistant/text_part.rb +52 -0
  46. data/lib/riffer/messages/assistant.rb +64 -17
  47. data/lib/riffer/params/any_of.rb +37 -9
  48. data/lib/riffer/params/param.rb +35 -14
  49. data/lib/riffer/params.rb +34 -19
  50. data/lib/riffer/providers/amazon_bedrock.rb +38 -5
  51. data/lib/riffer/providers/anthropic/client.rb +49 -0
  52. data/lib/riffer/providers/anthropic.rb +19 -452
  53. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +219 -0
  54. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +315 -0
  55. data/lib/riffer/providers/anthropic_compatible.rb +5 -0
  56. data/lib/riffer/providers/anthropic_vertex.rb +66 -0
  57. data/lib/riffer/providers/base.rb +19 -13
  58. data/lib/riffer/providers/gemini/client.rb +17 -85
  59. data/lib/riffer/providers/gemini.rb +213 -81
  60. data/lib/riffer/providers/google_cloud/client.rb +106 -0
  61. data/lib/riffer/providers/google_cloud.rb +99 -0
  62. data/lib/riffer/providers/open_ai.rb +21 -16
  63. data/lib/riffer/providers/repository.rb +2 -0
  64. data/lib/riffer/stream_events/server_tool_done.rb +21 -0
  65. data/lib/riffer/testing.rb +6 -0
  66. data/lib/riffer/version.rb +1 -1
  67. data/lib/riffer/wire/sse.rb +51 -0
  68. data/lib/riffer/wire.rb +31 -0
  69. data/lib/riffer.rb +20 -0
  70. data/rbs_collection.lock.yaml +24 -4
  71. data/sig/_private/faraday.rbs +8 -0
  72. data/sig/_private/googleauth.rbs +7 -0
  73. data/sig/generated/riffer/agent/run.rbs +5 -0
  74. data/sig/generated/riffer/agent/session.rbs +6 -0
  75. data/sig/generated/riffer/config/anthropic.rbs +6 -0
  76. data/sig/generated/riffer/config/future.rbs +29 -0
  77. data/sig/generated/riffer/config/gemini.rbs +6 -0
  78. data/sig/generated/riffer/config/google_cloud.rbs +28 -0
  79. data/sig/generated/riffer/config/pricing.rbs +0 -9
  80. data/sig/generated/riffer/config.rbs +10 -0
  81. data/sig/generated/riffer/deprecation/event.rbs +17 -0
  82. data/sig/generated/riffer/deprecation.rbs +27 -0
  83. data/sig/generated/riffer/http/client.rbs +59 -0
  84. data/sig/generated/riffer/http.rbs +4 -0
  85. data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
  86. data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
  87. data/sig/generated/riffer/messages/assistant.rbs +24 -11
  88. data/sig/generated/riffer/params/any_of.rbs +13 -5
  89. data/sig/generated/riffer/params/param.rbs +10 -5
  90. data/sig/generated/riffer/params.rbs +8 -4
  91. data/sig/generated/riffer/providers/amazon_bedrock.rbs +14 -2
  92. data/sig/generated/riffer/providers/anthropic/client.rbs +34 -0
  93. data/sig/generated/riffer/providers/anthropic.rbs +5 -124
  94. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +81 -0
  95. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +108 -0
  96. data/sig/generated/riffer/providers/anthropic_compatible.rbs +4 -0
  97. data/sig/generated/riffer/providers/anthropic_vertex.rbs +45 -0
  98. data/sig/generated/riffer/providers/base.rbs +5 -0
  99. data/sig/generated/riffer/providers/gemini/client.rbs +11 -34
  100. data/sig/generated/riffer/providers/gemini.rbs +66 -4
  101. data/sig/generated/riffer/providers/google_cloud/client.rbs +71 -0
  102. data/sig/generated/riffer/providers/google_cloud.rbs +64 -0
  103. data/sig/generated/riffer/providers/open_ai.rbs +7 -2
  104. data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
  105. data/sig/generated/riffer/testing.rbs +4 -0
  106. data/sig/generated/riffer/wire/sse.rbs +23 -0
  107. data/sig/generated/riffer/wire.rbs +17 -0
  108. data/sig/generated/riffer.rbs +15 -0
  109. data/sig/manual/riffer/deprecation.rbs +5 -0
  110. data/sig/manual/riffer/providers/anthropic_compatible/messages_api.rbs +8 -0
  111. data/sig/manual/riffer/providers/gemini.rbs +8 -0
  112. data/sig/manual/riffer/providers/google_cloud.rbs +8 -0
  113. data/sig/manual/riffer/wire.rbs +5 -0
  114. metadata +76 -5
  115. data/sig/_private/anthropic.rbs +0 -17
  116. data/sig/_private/riffer/providers/anthropic.rbs +0 -6
  117. data/sig/_private/riffer/providers/gemini.rbs +0 -7
@@ -0,0 +1,219 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ require "json"
5
+
6
+ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
7
+ # @rbs @tools: Array[singleton(Riffer::Tool)]
8
+ # @rbs @message: Hash[Symbol, untyped]
9
+ # @rbs @partial_json: Hash[Integer, String]
10
+ # @rbs @web_search_query: String?
11
+ # @rbs @completed: bool
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
+
19
+ #--
20
+ #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
21
+ def self.reasoning_part(block)
22
+ format = Riffer::Providers::AnthropicCompatible::MessagesAPI::REASONING_FORMAT
23
+
24
+ case block[:type]
25
+ when "thinking"
26
+ Riffer::Messages::Assistant::ReasoningPart.new(
27
+ type: :text,
28
+ text: block[:thinking],
29
+ signature: block[:signature],
30
+ format: format,
31
+ )
32
+ when "redacted_thinking"
33
+ Riffer::Messages::Assistant::ReasoningPart.new(type: :encrypted, data: block[:data], format: format)
34
+ end
35
+ end
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
+
51
+ #--
52
+ #: (tools: Array[singleton(Riffer::Tool)]) -> void
53
+ def initialize(tools:)
54
+ @tools = tools
55
+ @message = { content: [] }
56
+ @partial_json = {}
57
+ @web_search_query = nil
58
+ @completed = false
59
+ end
60
+
61
+ # Raises Riffer::APIError on a stream +error+ event.
62
+ #--
63
+ #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
64
+ def handle(event, yielder)
65
+ case event[:type]
66
+ when "message_start" then start_message(event)
67
+ when "content_block_start" then start_block(event)
68
+ when "content_block_delta" then apply_delta(event, yielder)
69
+ when "content_block_stop" then stop_block(event, yielder)
70
+ when "message_delta" then apply_message_delta(event)
71
+ when "message_stop" then stop_message(yielder)
72
+ when "error" then raise_stream_error(event)
73
+ end
74
+ end
75
+
76
+ # The caller reads finish reason and usage from here so it can price the usage.
77
+ #--
78
+ #: () -> Hash[Symbol, untyped]
79
+ def finish!
80
+ raise Riffer::IncompleteStreamError, "Anthropic stream ended without a message_stop event" unless @completed
81
+
82
+ @message
83
+ end
84
+
85
+ private
86
+
87
+ #--
88
+ #: (Hash[Symbol, untyped]) -> void
89
+ def start_message(event)
90
+ content = [] #: Array[Hash[Symbol, untyped]]
91
+ @message = event[:message].merge(content: content)
92
+ end
93
+
94
+ #--
95
+ #: (Hash[Symbol, untyped]) -> void
96
+ def start_block(event)
97
+ index = event[:index]
98
+ block = event[:content_block].dup
99
+ @message[:content][index] = block
100
+
101
+ case block[:type]
102
+ when "text" then block[:text] = +block[:text].to_s
103
+ when "thinking"
104
+ block[:thinking] = +block[:thinking].to_s
105
+ block[:signature] = block[:signature].to_s
106
+ end
107
+ end
108
+
109
+ #--
110
+ #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
111
+ def apply_delta(event, yielder)
112
+ index = event[:index]
113
+ block = @message[:content][index]
114
+ delta = event[:delta]
115
+
116
+ case delta[:type]
117
+ when "text_delta"
118
+ block[:text] << delta[:text]
119
+ yielder << Riffer::StreamEvents::TextDelta.new(delta[:text])
120
+ when "input_json_delta"
121
+ (@partial_json[index] ||= +"") << delta[:partial_json]
122
+ # server_tool_use input (web search) is not a riffer tool call.
123
+ return unless block[:type] == "tool_use"
124
+
125
+ yielder << Riffer::StreamEvents::ToolCallDelta.new(
126
+ item_id: block[:id],
127
+ name: Riffer::Wire.decode_tool_name(block[:name], tools: @tools),
128
+ arguments_delta: delta[:partial_json],
129
+ )
130
+ when "thinking_delta"
131
+ block[:thinking] << delta[:thinking]
132
+ yielder << Riffer::StreamEvents::ReasoningDelta.new(delta[:thinking])
133
+ when "signature_delta"
134
+ block[:signature] = delta[:signature]
135
+ end
136
+ end
137
+
138
+ #--
139
+ #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
140
+ def stop_block(event, yielder)
141
+ index = event[:index]
142
+ block = @message[:content][index]
143
+
144
+ case block[:type]
145
+ when "tool_use"
146
+ raw = @partial_json.delete(index).to_s
147
+ input = parse_input(raw)
148
+ block[:input] = input if input
149
+ yielder << Riffer::StreamEvents::ToolCallDone.new(
150
+ item_id: block[:id],
151
+ call_id: block[:id],
152
+ name: Riffer::Wire.decode_tool_name(block[:name], tools: @tools),
153
+ arguments: input ? input.to_json : raw,
154
+ )
155
+ when "thinking", "redacted_thinking"
156
+ part = self.class.reasoning_part(block) #: Riffer::Messages::Assistant::ReasoningPart
157
+ yielder << Riffer::StreamEvents::ReasoningDone.new(part)
158
+ when "server_tool_use"
159
+ block[:input] = parse_input(@partial_json.delete(index).to_s) || {}
160
+ yielder << Riffer::StreamEvents::ServerToolDone.new(self.class.server_tool_part(block))
161
+ return unless block[:name] == "web_search"
162
+
163
+ @web_search_query = block[:input]["query"]
164
+ yielder << Riffer::StreamEvents::WebSearchStatus.new("searching", query: @web_search_query)
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
+
169
+ yielder << Riffer::StreamEvents::WebSearchDone.new(@web_search_query || "", sources: web_search_sources(block))
170
+ @web_search_query = nil
171
+ end
172
+ end
173
+
174
+ #--
175
+ #: (Hash[Symbol, untyped]) -> void
176
+ def apply_message_delta(event)
177
+ @message.merge!(event[:delta] || {})
178
+ usage = event[:usage]
179
+ # Usage counts are cumulative; a field the delta omits keeps its start value.
180
+ @message[:usage] = (@message[:usage] || {}).merge(usage.compact) if usage
181
+ end
182
+
183
+ #--
184
+ #: (Riffer::Providers::_EventSink) -> void
185
+ def stop_message(yielder)
186
+ @completed = true
187
+ text = @message[:content].filter_map { |block| block[:text] if block[:type] == "text" }.join
188
+ yielder << Riffer::StreamEvents::TextDone.new(text) unless text.empty?
189
+ end
190
+
191
+ #--
192
+ #: (Hash[Symbol, untyped]) -> void
193
+ def raise_stream_error(event)
194
+ error = event[:error] || {}
195
+ raise Riffer::APIError.new("Anthropic stream error (#{error[:type]}): #{error[:message]}", body: event.to_json)
196
+ end
197
+
198
+ # A response cut off by max_tokens can end a block mid-input, leaving JSON
199
+ # that does not parse.
200
+ #--
201
+ #: (String) -> Hash[String, untyped]?
202
+ def parse_input(raw)
203
+ Riffer::Wire.parse_tool_arguments(raw)
204
+ rescue JSON::ParserError
205
+ nil
206
+ end
207
+
208
+ #--
209
+ #: (Hash[Symbol, untyped]) -> Array[Hash[Symbol, String?]]
210
+ def web_search_sources(block)
211
+ content = block[:content]
212
+ # An error result carries an object, not a list, as its content.
213
+ return [] unless content.is_a?(Array)
214
+
215
+ content.filter_map do |item|
216
+ { title: item[:title], url: item[:url] } if item[:type] == "web_search_result"
217
+ end
218
+ end
219
+ end
@@ -0,0 +1,315 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::Base
5
+ WEB_SEARCH_TOOL_TYPE = "web_search_20250305" #: String
6
+
7
+ FINISH_REASONS = {
8
+ "end_turn" => :stop,
9
+ "stop_sequence" => :stop,
10
+ "max_tokens" => :length,
11
+ "tool_use" => :tool_calls,
12
+ "refusal" => :content_filter,
13
+ "model_context_window_exceeded" => :context_window,
14
+ # A paused server-tool turn resumes only by re-sending the response; the
15
+ # agent loop does not do that, so it has no normalized equivalent.
16
+ "pause_turn" => :other,
17
+ }.freeze #: Hash[String, Symbol]
18
+
19
+ # Only parts carrying this tag are replayed, so reasoning captured by another
20
+ # adapter, whose signatures the Messages API may not accept, never reaches the
21
+ # request. Server tool parts and text parts that keep their block carry it too.
22
+ REASONING_FORMAT = "anthropic-messages-v1" #: String
23
+
24
+ #--
25
+ #: (?String?) -> singleton(Riffer::Skills::Adapter)
26
+ def self.skills_adapter(_model = nil)
27
+ Riffer::Skills::XmlAdapter
28
+ end
29
+
30
+ private
31
+
32
+ #--
33
+ #: (Symbol) -> Hash[Symbol, untyped]
34
+ def default_reasoning_options(level)
35
+ return { thinking: { type: "disabled" } } if level == :off
36
+
37
+ { thinking: { type: "adaptive" }, output_config: { effort: level.to_s } }
38
+ end
39
+
40
+ # Relative to the client's base URL.
41
+ #--
42
+ #: (String?, stream: bool) -> String
43
+ def messages_path(_model, stream:)
44
+ "v1/messages"
45
+ end
46
+
47
+ #--
48
+ #: (Hash[Symbol, untyped], stream: bool) -> Hash[Symbol, untyped]
49
+ def request_body(params, stream:)
50
+ stream ? params.merge(stream: true) : params
51
+ end
52
+
53
+ #--
54
+ #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
55
+ def execute_generate(params)
56
+ client.post(messages_path(params[:model], stream: false), request_body(params, stream: false))
57
+ end
58
+
59
+ #--
60
+ #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
61
+ def execute_stream(params, yielder)
62
+ stream = Stream.new(tools: @current_tools)
63
+ decoder = Riffer::Wire::SSE.new
64
+
65
+ client.post_stream(messages_path(params[:model], stream: true), request_body(params, stream: true)) do |chunk|
66
+ decoder.feed(chunk) { |data, _event| stream.handle(JSON.parse(data, symbolize_names: true), yielder) }
67
+ end
68
+
69
+ message = stream.finish!
70
+ yield_finish_reason(yielder, extract_finish_reason(message))
71
+ usage = extract_token_usage(message)
72
+ yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: usage) if usage
73
+ end
74
+
75
+ # Claude signs each thinking block over every block before it in the turn, so
76
+ # the blocks go back in the order they came.
77
+ #--
78
+ #: (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
79
+ def extract_parts(response)
80
+ content_blocks(response).filter_map do |block|
81
+ case block[:type]
82
+ when "text" then text_part(block)
83
+ when "tool_use"
84
+ Riffer::Messages::Assistant::ToolCall.new(
85
+ call_id: block[:id],
86
+ name: decode_tool_name(block[:name], tools: @current_tools),
87
+ arguments: (block[:input] || {}).to_json,
88
+ )
89
+ when "server_tool_use", Stream::SERVER_TOOL_RESULT_TYPE then Stream.server_tool_part(block)
90
+ else Stream.reasoning_part(block)
91
+ end
92
+ end
93
+ end
94
+
95
+ # The block is kept only when it carries citations, which point into the
96
+ # search results and go back with the text.
97
+ #--
98
+ #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::TextPart
99
+ def text_part(block)
100
+ citations = block[:citations]
101
+ return Riffer::Messages::Assistant::TextPart.new(block[:text].to_s) if citations.nil? || citations.empty?
102
+
103
+ Riffer::Messages::Assistant::TextPart.new(block[:text].to_s, data: JSON.generate(block), format: REASONING_FORMAT)
104
+ end
105
+
106
+ #--
107
+ #: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage?
108
+ def extract_token_usage(response)
109
+ usage = response[:usage]
110
+ return nil unless usage
111
+
112
+ cache_write = usage[:cache_creation_input_tokens]
113
+ cache_read = usage[:cache_read_input_tokens]
114
+
115
+ apply_pricing(
116
+ Riffer::Providers::TokenUsage.new(
117
+ # Anthropic's input_tokens excludes the cache buckets; TokenUsage's includes them.
118
+ input_tokens: (usage[:input_tokens] || 0) + (cache_write || 0) + (cache_read || 0),
119
+ output_tokens: usage[:output_tokens] || 0,
120
+ cache_write_tokens: cache_write,
121
+ cache_read_tokens: cache_read,
122
+ ),
123
+ )
124
+ end
125
+
126
+ #--
127
+ #: (Hash[Symbol, untyped]) -> Riffer::Providers::FinishReason?
128
+ def extract_finish_reason(response)
129
+ raw = response[:stop_reason]
130
+ return nil unless raw
131
+
132
+ Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(raw, :other), raw: raw)
133
+ end
134
+
135
+ #--
136
+ #: (Hash[Symbol, untyped]) -> Array[Hash[Symbol, untyped]]
137
+ def content_blocks(response)
138
+ response[:content] || []
139
+ end
140
+
141
+ #--
142
+ #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
143
+ def build_request_params(messages, model, options)
144
+ partitioned_messages = partition_messages(messages)
145
+ tools = options[:tools]
146
+ structured_output = options[:structured_output]
147
+ web_search = options[:web_search]
148
+ tags = options[:tags] || {}
149
+
150
+ max_tokens = options.fetch(:max_tokens, 4096)
151
+
152
+ params = {
153
+ model: model,
154
+ messages: partitioned_messages[:conversation],
155
+ max_tokens: max_tokens,
156
+ **options.except(:tools, :max_tokens, :structured_output, :web_search, :tags),
157
+ } #: Hash[Symbol, untyped]
158
+
159
+ params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
160
+
161
+ metadata = request_metadata(tags)
162
+ params[:metadata] = metadata if metadata
163
+
164
+ api_tools = [] #: Array[Hash[Symbol, untyped]]
165
+ api_tools.concat(tools.map { |t| convert_tool(t) }) if tools && !tools.empty?
166
+ api_tools << web_search_tool(web_search) if web_search
167
+
168
+ if structured_output
169
+ # The format wins over caller output_config keys because the run loop
170
+ # validates against it.
171
+ params[:output_config] = { **(params[:output_config] || {}), **structured_output_config(structured_output) }
172
+ end
173
+
174
+ params[:tools] = api_tools unless api_tools.empty?
175
+
176
+ params
177
+ end
178
+
179
+ #--
180
+ #: (Hash[String, untyped]) -> Hash[Symbol, untyped]?
181
+ def request_metadata(tags)
182
+ # The Messages API's only request-metadata field is metadata.user_id (opaque, no
183
+ # PII); all other tags survive only on spans.
184
+ user_id = tags["user_id"]
185
+ { user_id: user_id } if user_id
186
+ end
187
+
188
+ #--
189
+ #: (untyped) -> Hash[Symbol, untyped]
190
+ def web_search_tool(web_search)
191
+ tool = { type: WEB_SEARCH_TOOL_TYPE, name: "web_search" } #: Hash[Symbol, untyped]
192
+ tool.merge!(web_search) if web_search.is_a?(Hash)
193
+ tool
194
+ end
195
+
196
+ #--
197
+ #: (Riffer::Agent::StructuredOutput) -> Hash[Symbol, untyped]
198
+ def structured_output_config(structured_output)
199
+ # Strict schema makes optional fields nullable; otherwise Anthropic may
200
+ # return empty strings or whitespace instead of null.
201
+ {
202
+ format: {
203
+ type: "json_schema",
204
+ schema: structured_output.json_schema(strict: true),
205
+ },
206
+ }
207
+ end
208
+
209
+ #--
210
+ #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
211
+ def partition_messages(messages)
212
+ system_prompts = [] #: Array[Hash[Symbol, untyped]]
213
+ conversation_messages = [] #: Array[Hash[Symbol, untyped]]
214
+
215
+ messages.each do |message|
216
+ case message
217
+ when Riffer::Messages::System
218
+ system_prompts << { type: "text", text: message.content }
219
+ when Riffer::Messages::User
220
+ if message.files.empty?
221
+ conversation_messages << { role: "user", content: message.content }
222
+ else
223
+ content = [{ type: "text", text: message.content }]
224
+ message.files.each { |file| content << convert_file_part(file) }
225
+ conversation_messages << { role: "user", content: content }
226
+ end
227
+ when Riffer::Messages::Assistant
228
+ conversation_messages << convert_assistant(message)
229
+ when Riffer::Messages::Tool
230
+ conversation_messages << {
231
+ role: "user",
232
+ content: [{
233
+ type: "tool_result",
234
+ tool_use_id: message.tool_call_id,
235
+ content: message.content,
236
+ }],
237
+ }
238
+ end
239
+ end
240
+
241
+ {
242
+ system: system_prompts.empty? ? nil : system_prompts,
243
+ conversation: conversation_messages,
244
+ }
245
+ end
246
+
247
+ #--
248
+ #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
249
+ def convert_assistant(message)
250
+ { role: "assistant", content: message.parts.filter_map { |part| convert_part(part) } }
251
+ end
252
+
253
+ #--
254
+ #: (Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart) -> Hash[Symbol, untyped]?
255
+ def convert_part(part)
256
+ case part
257
+ when Riffer::Messages::Assistant::TextPart then convert_text_part(part)
258
+ when Riffer::Messages::Assistant::ToolCall
259
+ {
260
+ type: "tool_use",
261
+ id: part.call_id,
262
+ name: encode_tool_name(part.name),
263
+ input: parse_tool_arguments(part.arguments),
264
+ }
265
+ when Riffer::Messages::Assistant::ServerToolPart
266
+ JSON.parse(part.data, symbolize_names: true) if part.format == REASONING_FORMAT
267
+ when Riffer::Messages::Assistant::ReasoningPart
268
+ convert_reasoning_part(part) if part.format == REASONING_FORMAT
269
+ end
270
+ end
271
+
272
+ # The API rejects text blocks that are empty or only whitespace.
273
+ #--
274
+ #: (Riffer::Messages::Assistant::TextPart) -> Hash[Symbol, untyped]?
275
+ def convert_text_part(part)
276
+ return nil if part.text.strip.empty?
277
+
278
+ data = part.data
279
+ return JSON.parse(data, symbolize_names: true) if data && part.format == REASONING_FORMAT
280
+
281
+ { type: "text", text: part.text }
282
+ end
283
+
284
+ #--
285
+ #: (Riffer::Messages::Assistant::ReasoningPart) -> Hash[Symbol, untyped]
286
+ def convert_reasoning_part(part)
287
+ return { type: "redacted_thinking", data: part.data } if part.type == :encrypted
288
+
289
+ { type: "thinking", thinking: part.text.to_s, signature: part.signature }
290
+ end
291
+
292
+ #--
293
+ #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
294
+ def convert_file_part(file)
295
+ type = file.image? ? "image" : "document"
296
+
297
+ source = if file.url?
298
+ { type: "url", url: file.url }
299
+ else
300
+ { type: "base64", media_type: file.media_type, data: file.data }
301
+ end
302
+
303
+ { type: type, source: source }
304
+ end
305
+
306
+ #--
307
+ #: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
308
+ def convert_tool(tool)
309
+ {
310
+ name: encode_tool_name(tool.name),
311
+ description: tool.description,
312
+ input_schema: tool.parameters_schema(strict: true),
313
+ }
314
+ end
315
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Riffer::Providers::AnthropicCompatible
5
+ end
@@ -0,0 +1,66 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ # Claude models on Gemini Enterprise Agent Platform (formerly Vertex AI), through
5
+ # its rawPredict endpoints. Shares config.google_cloud and GoogleCloud::Client
6
+ # with the google_cloud provider.
7
+ class Riffer::Providers::AnthropicVertex < Riffer::Providers::AnthropicCompatible::MessagesAPI
8
+ # Matches the Anthropic provider. Agent Platform also accepts "vertex-2023-10-16".
9
+ DEFAULT_ANTHROPIC_VERSION = "2026-10-21" #: String
10
+
11
+ # Agent Platform model ids may carry an +@version+ suffix.
12
+ VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._@-]+\z/ #: Regexp
13
+
14
+ #--
15
+ #: () -> String
16
+ def self.semconv_provider_name
17
+ "gcp.vertex_ai"
18
+ end
19
+
20
+ private
21
+
22
+ #--
23
+ #: () -> untyped
24
+ def global_client
25
+ Riffer.config.google_cloud.client
26
+ end
27
+
28
+ #--
29
+ #: () -> Riffer::Providers::GoogleCloud::Client
30
+ def build_client
31
+ Riffer::Providers::GoogleCloud::Client.from_config(Riffer.config.google_cloud)
32
+ end
33
+
34
+ # Agent Platform takes the API version in the body, in place of the
35
+ # anthropic-version header. Override in a subclass to send another version.
36
+ #--
37
+ #: () -> String
38
+ def anthropic_version
39
+ DEFAULT_ANTHROPIC_VERSION
40
+ end
41
+
42
+ # The model goes in the URL rather than the body.
43
+ #--
44
+ #: (String?, stream: bool) -> String
45
+ def messages_path(model, stream:)
46
+ validate_model!(model)
47
+ "publishers/anthropic/models/#{model}:#{stream ? 'streamRawPredict' : 'rawPredict'}"
48
+ end
49
+
50
+ #--
51
+ #: (Hash[Symbol, untyped], stream: bool) -> Hash[Symbol, untyped]
52
+ def request_body(params, stream:)
53
+ body = { anthropic_version: anthropic_version, **params.except(:model) }
54
+ stream ? body.merge(stream: true) : body
55
+ end
56
+
57
+ #--
58
+ #: (String?) -> void
59
+ def validate_model!(model)
60
+ return if model.is_a?(String) && model.match?(VALID_MODEL_PATTERN)
61
+
62
+ raise Riffer::ArgumentError,
63
+ "Invalid model name: #{model.inspect}. Model must contain only alphanumeric characters, " \
64
+ "hyphens, dots, underscores, and @."
65
+ end
66
+ end
@@ -9,7 +9,7 @@ class Riffer::Providers::Base
9
9
  # @rbs @client: untyped
10
10
  # @rbs self.@semconv_provider_name: String?
11
11
 
12
- WIRE_SEPARATOR = "__" #: String
12
+ WIRE_SEPARATOR = Riffer::Wire::TOOL_NAME_SEPARATOR #: String
13
13
 
14
14
  #--
15
15
  #: (?String?) -> singleton(Riffer::Skills::Adapter)
@@ -45,9 +45,9 @@ class Riffer::Providers::Base
45
45
  in_chat_span(model, messages, options) do |span|
46
46
  response = execute_generate(params)
47
47
 
48
- content = extract_content(response)
49
- tool_calls = extract_tool_calls(response)
50
- reasoning = extract_reasoning(response)
48
+ parts = extract_parts(response)
49
+ content = parts.filter_map { |part| part.text if part.is_a?(Riffer::Messages::Assistant::TextPart) }.join
50
+ tool_calls = parts.grep(Riffer::Messages::Assistant::ToolCall) #: Array[Riffer::Messages::Assistant::ToolCall]
51
51
  token_usage = extract_token_usage(response)
52
52
  finish_reason = extract_finish_reason(response)
53
53
  structured_output = parse_structured_output(content) if options[:structured_output] && tool_calls.empty?
@@ -57,9 +57,7 @@ class Riffer::Providers::Base
57
57
  capture_output(span, content: content, tool_calls: tool_calls, finish_reason: finish_reason&.reason)
58
58
 
59
59
  Riffer::Messages::Assistant.new(
60
- content,
61
- tool_calls: tool_calls,
62
- reasoning: reasoning,
60
+ parts: parts,
63
61
  token_usage: token_usage,
64
62
  structured_output: structured_output,
65
63
  finish_reason: finish_reason&.reason,
@@ -135,14 +133,13 @@ class Riffer::Providers::Base
135
133
  #--
136
134
  #: (String) -> String
137
135
  def encode_tool_name(name)
138
- name.gsub("/", WIRE_SEPARATOR)
136
+ Riffer::Wire.encode_tool_name(name)
139
137
  end
140
138
 
141
139
  #--
142
140
  #: (String, tools: Array[singleton(Riffer::Tool)]) -> String
143
141
  def decode_tool_name(wire_name, tools:)
144
- tool = tools.find { |t| encode_tool_name(t.name) == wire_name }
145
- tool ? tool.name : wire_name
142
+ Riffer::Wire.decode_tool_name(wire_name, tools: tools)
146
143
  end
147
144
 
148
145
  #--
@@ -257,6 +254,17 @@ class Riffer::Providers::Base
257
254
  nil
258
255
  end
259
256
 
257
+ # Override when the provider interleaves blocks in one turn and needs them back in that order.
258
+ #--
259
+ #: (untyped) -> Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
260
+ def extract_parts(response)
261
+ Riffer::Messages::Assistant.new(
262
+ extract_content(response),
263
+ tool_calls: extract_tool_calls(response),
264
+ reasoning: extract_reasoning(response),
265
+ ).parts
266
+ end
267
+
260
268
  #--
261
269
  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
262
270
  def extract_reasoning(_response)
@@ -417,9 +425,7 @@ class Riffer::Providers::Base
417
425
  #--
418
426
  #: (String) -> Hash[String, untyped]
419
427
  def parse_tool_arguments(arguments)
420
- return {} if arguments.empty?
421
-
422
- JSON.parse(arguments)
428
+ Riffer::Wire.parse_tool_arguments(arguments)
423
429
  end
424
430
 
425
431
  #--