crystil 0.5.0 → 0.7.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 (43) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +115 -42
  3. data/LICENSE +1 -1
  4. data/README.md +11 -3
  5. data/lib/crystil/callables.rb +24 -0
  6. data/lib/crystil/client.rb +7 -0
  7. data/lib/crystil/collector.rb +127 -4
  8. data/lib/crystil/sentinel.rb +2 -19
  9. data/lib/crystil/version.rb +1 -1
  10. data/lib/crystil/wrappers/anthropic.rb +151 -14
  11. data/lib/crystil/wrappers/base.rb +29 -28
  12. data/lib/crystil/wrappers/blocked_call.rb +52 -0
  13. data/lib/crystil/wrappers/constants.rb +3 -0
  14. data/lib/crystil/wrappers/deep_copy.rb +52 -0
  15. data/lib/crystil/wrappers/event_stream.rb +200 -0
  16. data/lib/crystil/wrappers/geminiai.rb +98 -41
  17. data/lib/crystil/wrappers/google.rb +18 -18
  18. data/lib/crystil/wrappers/groq.rb +96 -108
  19. data/lib/crystil/wrappers/openai.rb +118 -101
  20. data/lib/crystil/wrappers/ruby_llm.rb +150 -101
  21. data/lib/crystil/wrappers/ruby_llm_query.rb +176 -0
  22. data/lib/crystil/wrappers/ruby_llm_record.rb +105 -0
  23. data/lib/crystil/wrappers/ruby_llm_response.rb +148 -0
  24. data/lib/crystil/wrappers/stopped_call.rb +88 -0
  25. data/lib/crystil.rb +2 -1
  26. data/sig/crystil/callables.rbs +6 -0
  27. data/sig/crystil/client.rbs +2 -0
  28. data/sig/crystil/collector.rbs +33 -1
  29. data/sig/crystil/sentinel.rbs +0 -1
  30. data/sig/crystil/wrappers/anthropic.rbs +12 -0
  31. data/sig/crystil/wrappers/base.rbs +9 -4
  32. data/sig/crystil/wrappers/blocked_call.rbs +15 -0
  33. data/sig/crystil/wrappers/constants.rbs +1 -0
  34. data/sig/crystil/wrappers/deep_copy.rbs +12 -0
  35. data/sig/crystil/wrappers/event_stream.rbs +24 -0
  36. data/sig/crystil/wrappers/geminiai.rbs +11 -0
  37. data/sig/crystil/wrappers/openai.rbs +12 -0
  38. data/sig/crystil/wrappers/ruby_llm.rbs +11 -4
  39. data/sig/crystil/wrappers/ruby_llm_query.rbs +35 -0
  40. data/sig/crystil/wrappers/ruby_llm_record.rbs +21 -0
  41. data/sig/crystil/wrappers/ruby_llm_response.rbs +39 -0
  42. data/sig/crystil/wrappers/stopped_call.rbs +26 -0
  43. metadata +18 -2
@@ -33,6 +33,53 @@ module Crystil
33
33
  client
34
34
  end
35
35
 
36
+ # How many arguments a stream callback takes, worked out as ruby-openai's
37
+ # `OpenAI::Stream` does, so it gets what it would get without Crystil. A
38
+ # variadic `call(*args)` counts as 1; declare `call(chunk, event = nil)` for both.
39
+ def self.callback_arity(callback)
40
+ callback.is_a?(Proc) ? callback.arity.abs : callback.method(:call).arity.abs
41
+ end
42
+
43
+ # The events that end a Responses stream, each carrying the whole `Response`.
44
+ TERMINAL_EVENT_TYPES = %w[response.completed response.incomplete response.failed].freeze
45
+ NO_TERMINAL_EVENT_MESSAGE = "Responses API stream ended without a response.completed, " \
46
+ "response.incomplete or response.failed event"
47
+
48
+ # The response a finished Responses stream records: the latest terminal event's `response`,
49
+ # which carries the usage; or, when only an `error` event came, that error; or nil.
50
+ def self.finished_response(events)
51
+ terminal = events.reverse.find { |event| TERMINAL_EVENT_TYPES.include?(event["type"]) }
52
+ return terminal["response"] if terminal
53
+
54
+ error_event = events.find { |event| event["type"] == "error" }
55
+ error_event && { "error" => error_details(error_event) }
56
+ end
57
+
58
+ # OpenAI's `error` event carries `code`, `message` and `param` at its top level.
59
+ # An error that arrives nested under `error` is taken as it is.
60
+ def self.error_details(error_event)
61
+ nested = error_event["error"]
62
+ nested.is_a?(Hash) ? nested : error_event.slice("code", "message", "param")
63
+ end
64
+
65
+ # How a Responses call is recorded: failed when its response says so, or holds only an error.
66
+ # Returns the status and the error message to record.
67
+ def self.outcome(response)
68
+ return ["succeeded", nil] unless response.is_a?(Hash)
69
+
70
+ status = response["status"]
71
+ return ["succeeded", nil] unless status == "failed" || (status.nil? && response.key?("error"))
72
+
73
+ ["failed", response.dig("error", "message") || "OpenAI response status: #{status || "unknown"}"]
74
+ end
75
+
76
+ # The response a Responses stream had reached when it stopped: the `response`
77
+ # its latest event carried (`response.created`, `response.in_progress`), or nil.
78
+ def self.response_so_far(events)
79
+ latest = events&.reverse&.find { |event| event["response"].is_a?(Hash) }
80
+ latest && latest["response"]
81
+ end
82
+
36
83
  private
37
84
 
38
85
  def wrap_responses_method(client)
@@ -52,12 +99,13 @@ module Crystil
52
99
  start_time = Time.now
53
100
  version = defined?(::OpenAI::VERSION) ? ::OpenAI::VERSION : nil
54
101
 
55
- sentinel = instance_variable_get(:@crystil_sentinel)
56
- sentinel&.raise_if_irrelevant!(
102
+ crystil_raise_if_irrelevant!(
57
103
  title: OPENAI_CLIENT_TITLE,
58
104
  request: parameters,
105
+ start_time: start_time,
59
106
  version: version
60
107
  )
108
+ passed_sentinel = true
61
109
 
62
110
  # Dup before mutating so we don't replace the caller's :stream key with our
63
111
  # internal wrapping proc — the caller's hash should be unchanged after the call.
@@ -67,92 +115,56 @@ module Crystil
67
115
 
68
116
  if streaming
69
117
  accumulated_events = []
70
- user_callback = parameters[:stream]
71
- # Determine how many arguments to forward to the user's callback.
72
- # .arity returns negative values for methods with optional/splat params
73
- # (e.g. def call(*args) => -1, def call(a, b=nil) => -2), so .abs gives
74
- # us the minimum required argument count. For fixed-arity procs/lambdas
75
- # this is exact. Note: a variadic callable (def call(*args)) has arity -1,
76
- # so .abs yields 1 — the event_type argument will be silently dropped for
77
- # that signature. Use def call(event, event_type = nil) to receive both.
78
- user_callback_arity =
79
- case user_callback
80
- when Proc
81
- user_callback.arity.abs
82
- else
83
- user_callback.method(:call).arity.abs
84
- end
118
+ user_callback_arity = Crystil::Wrappers::OpenAI.callback_arity(parameters[:stream])
119
+ caller_block = StoppedCall::CallerBlock.new(parameters[:stream])
85
120
 
86
121
  parameters[:stream] = proc do |chunk, event_type|
87
122
  accumulated_events << chunk if chunk.is_a?(Hash)
88
- user_callback.call(*[chunk, event_type].first(user_callback_arity))
123
+ caller_block.call(*[chunk, event_type].first(user_callback_arity))
89
124
  end
90
125
  end
91
126
 
92
127
  response = original_create(parameters: parameters)
93
128
 
94
- # Default to the returned response; for streaming, replace it with the
95
- # full response from the terminal response.completed event.
96
- final_response = response
97
-
98
- if streaming
99
- error_event = accumulated_events.find { |e| e["type"] == "error" }
100
- if error_event
101
- final_response = {
102
- "status" => "failed",
103
- "error" => error_event["error"]
104
- }
105
- end
106
-
107
- # Extract the full response from the terminal response.completed event.
108
- # A missing terminal event means the stream was interrupted.
109
- completed = accumulated_events.find { |e| e["type"] == "response.completed" }
110
- unless completed || error_event
111
- raise StreamError,
112
- "Responses API stream ended without response.completed event"
113
- end
114
-
115
- final_response = completed["response"] if completed && !error_event
129
+ # For streaming, the full response comes from the stream's events.
130
+ final_response = streaming ? Crystil::Wrappers::OpenAI.finished_response(accumulated_events) : response
131
+
132
+ recorded = true
133
+ if streaming && final_response.nil?
134
+ # Recorded as failed, but the call returns as the gem's did: the record is never why it fails.
135
+ crystil_submit_error_analytics(
136
+ method: :create, args: [], kwargs: parameters,
137
+ error: StreamError.new(Crystil::Wrappers::OpenAI::NO_TERMINAL_EVENT_MESSAGE),
138
+ start_time: start_time, end_time: Time.now, title: OPENAI_CLIENT_TITLE, version: version
139
+ )
140
+ else
141
+ # Only a failed response, or one holding only an error, is recorded as failed;
142
+ # an incomplete one (a `max_output_tokens` cap, the content filter) succeeded.
143
+ analytics_status, analytics_exception = Crystil::Wrappers::OpenAI.outcome(final_response)
144
+ crystil_submit_analytics(
145
+ method: :create, args: [], kwargs: parameters, response: final_response,
146
+ start_time: start_time, end_time: Time.now, title: OPENAI_CLIENT_TITLE, version: version,
147
+ status: analytics_status, exception: analytics_exception
148
+ )
116
149
  end
117
150
 
118
- # Treat only an explicit failed response status as failed analytics.
119
- # Other non-exceptional statuses are still recorded as succeeded.
120
- response_status = final_response.is_a?(Hash) ? final_response["status"] : nil
121
- analytics_status = response_status == "failed" ? "failed" : "succeeded"
122
- analytics_exception =
123
- if analytics_status == "failed"
124
- final_response.dig("error", "message") ||
125
- "OpenAI response status: #{response_status || "unknown"}"
126
- end
127
-
128
- crystil_submit_analytics(
129
- method: :create,
130
- args: [],
131
- kwargs: parameters,
132
- response: final_response,
133
- start_time: start_time,
134
- end_time: Time.now,
135
- title: OPENAI_CLIENT_TITLE,
136
- version: version,
137
- status: analytics_status,
138
- exception: analytics_exception
139
- )
140
-
141
151
  response
142
- rescue CrystilRequestInterceptedError => e
143
- raise e
144
- rescue StandardError => e
145
- crystil_submit_error_analytics(
146
- method: :create,
147
- args: [],
148
- kwargs: parameters,
149
- error: e,
150
- start_time: start_time,
151
- end_time: Time.now,
152
- title: OPENAI_CLIENT_TITLE,
153
- version: version
154
- )
152
+ rescue SignalException, StandardError => e
153
+ # A block from a nested call falls through: this call reached the provider, so it failed.
154
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
155
+
156
+ error = e
155
157
  raise e
158
+ ensure
159
+ # Recorded here, not in the rescue: a `break` or `throw` from the app's callback raises nothing.
160
+ if !recorded && passed_sentinel
161
+ crystil_submit_unfinished_analytics(
162
+ error, caller_block,
163
+ method: :create, kwargs: parameters,
164
+ received: Crystil::Wrappers::OpenAI.response_so_far(accumulated_events),
165
+ start_time: start_time, title: OPENAI_CLIENT_TITLE, version: version
166
+ )
167
+ end
156
168
  end
157
169
  end
158
170
  end
@@ -177,32 +189,38 @@ module Crystil
177
189
  start_time = Time.now
178
190
  version = defined?(::OpenAI::VERSION) ? ::OpenAI::VERSION : nil
179
191
 
180
- sentinel = instance_variable_get(:@crystil_sentinel)
181
- sentinel&.raise_if_irrelevant!(
192
+ crystil_raise_if_irrelevant!(
182
193
  title: OPENAI_CLIENT_TITLE,
183
194
  request: parameters,
195
+ start_time: start_time,
184
196
  version: version
185
197
  )
198
+ passed_sentinel = true
199
+
200
+ # Dup before mutating so the caller's hash keeps its own callback; a reused
201
+ # hash would otherwise hand ours back, to be wrapped again on every call.
202
+ parameters = parameters.dup
186
203
 
187
- # Detect streaming and wrap callback to accumulate chunks
188
- streaming = parameters[:stream].is_a?(Proc)
204
+ # Detect streaming and wrap callback to accumulate chunks. Like ruby-openai,
205
+ # treat anything that responds to `call` as a stream callback.
206
+ streaming = parameters[:stream].respond_to?(:call)
189
207
  accumulated_response = {} if streaming
190
208
 
191
209
  if streaming
192
210
  # Configure streaming to include usage (matches Python SDK behavior).
193
211
  # A caller-set value (true or false) wins — we only force `true`
194
212
  # when the key is absent.
195
- parameters[:stream_options] ||= {}
196
- parameters[:stream_options][:include_usage] = true unless parameters[:stream_options].key?(:include_usage)
213
+ parameters[:stream_options] = { include_usage: true }.merge(parameters[:stream_options] || {})
197
214
 
198
- user_callback = parameters[:stream]
199
- parameters[:stream] = proc do |chunk, bytesize|
215
+ user_callback_arity = Crystil::Wrappers::OpenAI.callback_arity(parameters[:stream])
216
+ caller_block = StoppedCall::CallerBlock.new(parameters[:stream])
217
+ parameters[:stream] = proc do |chunk, event|
200
218
  # Normalize chunk to match Python SDK format (add missing delta keys with nil)
201
219
  normalized_chunk = crystil_normalize_openai_chunk(chunk)
202
220
  # Accumulate chunk (merge into accumulated_response)
203
221
  crystil_merge_streaming_chunk(accumulated_response, normalized_chunk)
204
- # Call user's original callback with original chunk (don't modify user's data)
205
- user_callback.call(chunk, bytesize)
222
+ # Pass the user's callback the original chunk, and only as many arguments as it takes.
223
+ caller_block.call(*[chunk, event].first(user_callback_arity))
206
224
  end
207
225
  end
208
226
 
@@ -212,7 +230,7 @@ module Crystil
212
230
  # Use accumulated response for streaming, otherwise use returned response
213
231
  final_response = streaming ? accumulated_response : response
214
232
 
215
- # Submit analytics
233
+ recorded = true
216
234
  crystil_submit_analytics(
217
235
  method: :chat,
218
236
  args: [],
@@ -225,22 +243,21 @@ module Crystil
225
243
  )
226
244
 
227
245
  response
228
- rescue CrystilRequestInterceptedError => e
229
- # We don't want to send intercepts to collector
230
- raise e
231
- rescue StandardError => e
232
- crystil_submit_error_analytics(
233
- method: :chat,
234
- args: [],
235
- kwargs: parameters,
236
- error: e,
237
- start_time: start_time,
238
- end_time: Time.now,
239
- title: OPENAI_CLIENT_TITLE,
240
- version: version
241
- )
246
+ rescue SignalException, StandardError => e
247
+ # A block from a nested call falls through: this call reached the provider, so it failed.
248
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
242
249
 
250
+ error = e
243
251
  raise e
252
+ ensure
253
+ # Recorded here, not in the rescue: a `break` or `throw` from the app's callback raises nothing.
254
+ if !recorded && passed_sentinel
255
+ crystil_submit_unfinished_analytics(
256
+ error, caller_block,
257
+ method: :chat, kwargs: parameters, received: accumulated_response,
258
+ start_time: start_time, title: OPENAI_CLIENT_TITLE, version: version
259
+ )
260
+ end
244
261
  end
245
262
  end
246
263
  end
@@ -1,6 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "constants"
4
+ require_relative "ruby_llm_query"
5
+ require_relative "ruby_llm_response"
6
+ require_relative "ruby_llm_record"
4
7
 
5
8
  module Crystil
6
9
  module Wrappers
@@ -9,6 +12,8 @@ module Crystil
9
12
  # Returns raw response and raw formatted query to backend so that the existing
10
13
  # extractors can be used.
11
14
  class RubyLLM
15
+ include RubyLLMRecord
16
+
12
17
  def initialize(config, collector, sentinel = nil)
13
18
  @config = config
14
19
  @collector = collector
@@ -18,6 +23,13 @@ module Crystil
18
23
  def register(client)
19
24
  validate_client!(client)
20
25
 
26
+ # An agent forwards `ask` to its chat, whose `ask` calls the chat's own
27
+ # `complete`, so the chat is what gets wrapped. It may be a Rails record.
28
+ if agent?(client)
29
+ register(client.chat)
30
+ return client
31
+ end
32
+
21
33
  # Prevent double registration
22
34
  return client if client.instance_variable_defined?(:@crystil_registered)
23
35
 
@@ -27,8 +39,11 @@ module Crystil
27
39
  client.instance_variable_set(:@crystil_sentinel, @sentinel)
28
40
  client.instance_variable_set(:@crystil_registered, true)
29
41
 
30
- # Ask method handles both streaming and non-streaming cases unlike some others.
31
- wrap_ask_method(client)
42
+ if client.respond_to?(:to_llm)
43
+ wrap_record(client)
44
+ else
45
+ wrap_complete_method(client)
46
+ end
32
47
 
33
48
  client
34
49
  end
@@ -36,134 +51,168 @@ module Crystil
36
51
  private
37
52
 
38
53
  def validate_client!(client)
39
- return if client.respond_to?(:ask)
54
+ return if client.respond_to?(:complete)
40
55
 
41
56
  raise RegistrationError,
42
- "Client does not appear to be a valid RubyLLM client (missing ask method)"
57
+ "Client does not appear to be a valid RubyLLM client (missing complete method)"
58
+ end
59
+
60
+ def agent?(client)
61
+ return false unless defined?(::RubyLLM::Agent)
62
+
63
+ client.is_a?(::RubyLLM::Agent)
43
64
  end
44
65
 
45
- def wrap_ask_method(client)
66
+ # Every call to the provider goes through `complete`: `ask` and its alias
67
+ # `say` add the user's message to `messages`, then call it, and a caller can
68
+ # do the same with `add_message`. Handles streaming and non-streaming alike.
69
+ def wrap_complete_method(chat)
46
70
  # Capture the wrapper instance in a local variable so it's accessible as a closure
47
71
  # inside the block, where self will no longer refer to it.
48
72
  wrapper = self
49
73
 
50
- client.singleton_class.class_eval do
74
+ chat.singleton_class.class_eval do
51
75
  include Base
52
76
 
53
- alias_method :original_ask, :ask
77
+ alias_method :original_complete, :complete
54
78
 
55
- define_method(:ask) do |message, with: nil, &block|
79
+ define_method(:complete) do |*args, **kwargs, &block|
80
+ # Each level of `complete` makes one provider call: a tool round calls
81
+ # `complete` again from inside this one. So every level records its own
82
+ # round, and only the outermost asks Sentinel.
83
+ outermost = !@crystil_completing
84
+ @crystil_completing = true
85
+ @crystil_round_starts = [] if outermost
56
86
  start_time = Time.now
57
- query = {} # Fallback for error analytics if an exception occurs before build_query completes
87
+ level = @crystil_round_starts.size
88
+ @crystil_round_starts << start_time
89
+ history_size = messages.size
90
+ query = {} # Fallback for error analytics if an exception occurs before the query is built
58
91
  # Version reported is RubyLLM's, not the underlying provider's — RubyLLM is the
59
92
  # meta-wrapper Crystil sees; the native provider gem may not even be loaded.
60
93
  version = defined?(::RubyLLM::VERSION) ? ::RubyLLM::VERSION : nil
61
-
62
- sentinel = instance_variable_get(:@crystil_sentinel)
63
- provider = model.provider
64
- # Telemetry invariant: `conversation.client.title` is never nil.
65
- # `model.provider` should always return a non-empty string for
66
- # well-formed RubyLLM models, but fall back to the meta-wrapper
67
- # name (matches JS's pattern of "fallback to the SDK family
68
- # name") if it ever isn't.
69
- title = case provider
70
- when "gemini" then GOOGLE_CLIENT_TITLE
71
- when nil, "" then RUBY_LLM_PROVIDER
72
- else provider
73
- end
74
-
75
- # Capture existing messages (e.g. system instruction) before the call
76
- # adds the new user message to history.
77
- existing_msgs = messages.map { |m| { role: m.role.to_s, content: m.content.to_s } }
78
- all_msgs = existing_msgs + [{ role: "user", content: message.to_s }]
79
-
80
- # Build a query in the provider's native format so the backend extractor can parse it.
81
- query = wrapper.send(:build_query, provider, model.id, all_msgs, tools)
82
-
83
- # Pass the actual provider title (e.g. "anthropic", "openai", "google") so the
84
- # sentinel backend can route to the correct classifier for this request format.
85
- sentinel&.raise_if_irrelevant!(title: title, request: query, version: version)
86
-
87
- response = original_ask(message, with: with, &block)
88
-
89
- crystil_submit_analytics(
90
- method: :ask,
91
- args: [],
92
- kwargs: query,
93
- response: response.raw&.body,
94
- start_time: start_time,
95
- end_time: Time.now,
96
- title: title,
97
- provider: RUBY_LLM_PROVIDER,
98
- version: version
99
- )
100
-
94
+ title = wrapper.send(:client_title, model.provider)
95
+ # A block streams the reply; the gem passes it on to each tool round.
96
+ round = { start_time: start_time, level: level, title: title, version: version, streamed: !block.nil? }
97
+
98
+ # A query in the provider's native format, so the backend extractor can parse it.
99
+ # It is the history this level's provider call is sent, new user turn included.
100
+ # Nil when it cannot be built: the round then records no messages, and Sentinel is skipped.
101
+ built = RubyLLMQuery.for_chat(self)
102
+ round[:query] = built || RubyLLMQuery.empty_query(model.provider, model.id)
103
+ query = RubyLLMQuery.mark_streamed(round[:query], round[:streamed], model.provider)
104
+
105
+ # A Rails record's `ask` asks Sentinel itself, before it saves the user's message.
106
+ checked_by_record = @crystil_turn_checked
107
+ @crystil_turn_checked = false
108
+ if outermost && !checked_by_record && built
109
+ # The provider title (e.g. "anthropic") routes Sentinel to the matching classifier.
110
+ crystil_raise_if_irrelevant!(
111
+ title: title, request: round[:query], query: query, start_time: start_time,
112
+ provider: RUBY_LLM_PROVIDER, version: version
113
+ )
114
+ end
115
+ passed_sentinel = true
116
+
117
+ # The app's block streams the reply; it is wrapped to keep what arrives, for a stream the app stops.
118
+ # A tool round gets the outer level's wrapper back from the gem, so it wraps the app's own block.
119
+ app_block = @crystil_chunks&.made?(block) ? @crystil_chunks.app_block : block
120
+ chunks = app_block && RubyLLMResponse::Chunks.new(app_block)
121
+ @crystil_chunks = chunks
122
+ response = original_complete(*args, **kwargs, &chunks)
123
+ recorded = true
124
+ # A `Halt` from a tool has no `raw`, so the round is read from the history.
125
+ wrapper.send(:record_round, self, history_size, round, chunks)
101
126
  response
102
- rescue CrystilRequestInterceptedError => e
103
- raise e
104
- rescue StandardError => e
105
- crystil_submit_error_analytics(
106
- method: :ask,
107
- args: [],
108
- kwargs: query,
109
- error: e,
110
- start_time: start_time,
111
- end_time: Time.now,
112
- title: title,
113
- provider: RUBY_LLM_PROVIDER,
114
- version: version
115
- )
127
+ rescue SignalException, StandardError => e
128
+ if crystil_block_already_recorded?(e, passed_sentinel)
129
+ # Sentinel judges only the newest user message, so one left in history
130
+ # would reach the provider with the next allowed turn.
131
+ wrapper.send(:remove_blocked_message, self)
132
+ raise e
133
+ end
134
+
135
+ error = e
116
136
  raise e
137
+ ensure
138
+ # Recorded here, not in the rescue: a `break` or `throw` from the app's block raises nothing.
139
+ if !recorded && passed_sentinel
140
+ wrapper.send(:record_unfinished, self, error, chunks, history_size, round, query)
141
+ end
142
+ if outermost
143
+ @crystil_completing = false
144
+ @crystil_chunks = nil
145
+ end
117
146
  end
118
147
  end
119
148
  end
120
149
 
121
- # Dispatches to the appropriate provider-native query builder.
122
- def build_query(provider, model_id, messages, tools)
123
- if provider == "gemini"
124
- build_google_query(model_id, messages, tools)
125
- else
126
- # Anthropic and OpenAI have the same query format
127
- build_messages_query(model_id, messages, tools)
128
- end
150
+ # Records one level's round from the reply its provider call added to the history:
151
+ # the first assistant message after `history_size`. It ends when the next level began,
152
+ # if one did, or now. False when the round got no reply. A telemetry error never escapes.
153
+ def record_round(chat, history_size, round, chunks)
154
+ reply = chat.messages.drop(history_size).find { |m| m.role.to_s == "assistant" }
155
+ return false unless reply
156
+
157
+ next_start = chat.instance_variable_get(:@crystil_round_starts)[round[:level] + 1]
158
+ query = RubyLLMQuery.mark_streamed(round[:query], round[:streamed], chat.model.provider)
159
+ chat.crystil_submit_analytics(
160
+ method: :complete, args: [], kwargs: query, response: RubyLLMResponse.build(reply, chunks&.model_id),
161
+ start_time: round[:start_time], end_time: next_start || Time.now,
162
+ title: round[:title], provider: RUBY_LLM_PROVIDER, version: round[:version]
163
+ )
164
+ true
165
+ rescue StandardError => e
166
+ warn "Crystil: Failed to record a RubyLLM round: #{e.message}"
167
+ true
129
168
  end
130
169
 
131
- # Builds an OpenAI-compatible query (used for Anthropic and OpenAI providers).
132
- def build_messages_query(model_id, messages, tools)
133
- query = { model: model_id, messages: messages }
134
- unless tools.empty?
135
- query[:tools] = tools.values.map do |t|
136
- { name: t.name, description: t.description, parameters: t.params_schema }
137
- end
138
- end
139
- query
170
+ # Records a level whose `complete` did not return. One whose provider call got its
171
+ # reply records that round, since what ended it came later, in a tool or a later
172
+ # round, which records itself. Otherwise the call was stopped by the app or failed.
173
+ def record_unfinished(chat, error, chunks, history_size, round, query)
174
+ return if round.nil? || record_round(chat, history_size, round, chunks)
175
+
176
+ chat.crystil_submit_unfinished_analytics(
177
+ error, chunks&.caller_block,
178
+ method: :complete, kwargs: query, received: chunks&.reply_so_far,
179
+ start_time: round[:start_time], provider: RUBY_LLM_PROVIDER, title: round[:title], version: round[:version]
180
+ )
140
181
  end
141
182
 
142
- # Builds a Google-native query with contents/systemInstruction structure.
143
- def build_google_query(model_id, messages, tools)
144
- system_msgs = messages.select { |m| m[:role] == "system" }
145
- content_msgs = messages.reject { |m| m[:role] == "system" }
183
+ # Takes the user message Sentinel just blocked back out of the chat's history.
184
+ # For a Rails record, that history is the saved rows, so the row goes too.
185
+ # A failure here is only warned about, so it never replaces the block.
186
+ def remove_blocked_message(chat)
187
+ return unless user_message?(chat.messages.last)
146
188
 
147
- query = {
148
- model: model_id,
149
- contents: content_msgs.map do |m|
150
- google_role = m[:role] == "assistant" ? "model" : m[:role]
151
- { role: google_role, parts: [{ text: m[:content] }] }
152
- end
153
- }
189
+ blocked = chat.messages.pop
190
+ saved_turn = chat.instance_variable_get(:@crystil_saved_turn)
191
+ return unless saved_turn && saved_turn[:message].equal?(blocked)
154
192
 
155
- if system_msgs.any?
156
- system_text = system_msgs.map { |m| m[:content] }.join("\n")
157
- query[:systemInstruction] = { parts: [{ text: system_text }] }
158
- end
193
+ # Through the association, so the row also leaves the rows the record has loaded.
194
+ saved_turn[:rows].destroy(saved_turn[:row])
195
+ rescue StandardError => e
196
+ warn "Crystil: Failed to remove a blocked RubyLLM message: #{e.message}"
197
+ end
159
198
 
160
- unless tools.empty?
161
- query[:tools] = tools.values.map do |t|
162
- { name: t.name, description: t.description, parameters: t.params_schema }
163
- end
164
- end
199
+ def sentinel_on?
200
+ !@sentinel.nil? && @config.raise_if_irrelevant
201
+ end
165
202
 
166
- query
203
+ def user_message?(message)
204
+ !message.nil? && message.role.to_s == "user"
205
+ end
206
+
207
+ # Telemetry invariant: `conversation.client.title` is never nil. `model.provider`
208
+ # should always be a non-empty string for well-formed RubyLLM models, but fall back
209
+ # to the meta-wrapper name (JS's "fallback to the SDK family name") if it ever isn't.
210
+ def client_title(provider)
211
+ case provider
212
+ when "gemini" then GOOGLE_CLIENT_TITLE
213
+ when nil, "" then RUBY_LLM_PROVIDER
214
+ else provider
215
+ end
167
216
  end
168
217
  end
169
218
  end