crystil 0.6.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 (41) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +110 -72
  3. data/README.md +6 -9
  4. data/lib/crystil/callables.rb +24 -0
  5. data/lib/crystil/client.rb +7 -0
  6. data/lib/crystil/collector.rb +127 -4
  7. data/lib/crystil/sentinel.rb +2 -19
  8. data/lib/crystil/version.rb +1 -1
  9. data/lib/crystil/wrappers/anthropic.rb +37 -36
  10. data/lib/crystil/wrappers/base.rb +25 -28
  11. data/lib/crystil/wrappers/blocked_call.rb +52 -0
  12. data/lib/crystil/wrappers/constants.rb +3 -0
  13. data/lib/crystil/wrappers/deep_copy.rb +52 -0
  14. data/lib/crystil/wrappers/event_stream.rb +21 -26
  15. data/lib/crystil/wrappers/geminiai.rb +57 -36
  16. data/lib/crystil/wrappers/google.rb +18 -18
  17. data/lib/crystil/wrappers/groq.rb +89 -101
  18. data/lib/crystil/wrappers/openai.rb +118 -101
  19. data/lib/crystil/wrappers/ruby_llm.rb +150 -101
  20. data/lib/crystil/wrappers/ruby_llm_query.rb +176 -0
  21. data/lib/crystil/wrappers/ruby_llm_record.rb +105 -0
  22. data/lib/crystil/wrappers/ruby_llm_response.rb +148 -0
  23. data/lib/crystil/wrappers/stopped_call.rb +88 -0
  24. data/lib/crystil.rb +2 -1
  25. data/sig/crystil/callables.rbs +6 -0
  26. data/sig/crystil/client.rbs +2 -0
  27. data/sig/crystil/collector.rbs +33 -1
  28. data/sig/crystil/sentinel.rbs +0 -1
  29. data/sig/crystil/wrappers/base.rbs +7 -5
  30. data/sig/crystil/wrappers/blocked_call.rbs +15 -0
  31. data/sig/crystil/wrappers/constants.rbs +1 -0
  32. data/sig/crystil/wrappers/deep_copy.rbs +12 -0
  33. data/sig/crystil/wrappers/event_stream.rbs +2 -2
  34. data/sig/crystil/wrappers/geminiai.rbs +2 -0
  35. data/sig/crystil/wrappers/openai.rbs +12 -0
  36. data/sig/crystil/wrappers/ruby_llm.rbs +11 -4
  37. data/sig/crystil/wrappers/ruby_llm_query.rbs +35 -0
  38. data/sig/crystil/wrappers/ruby_llm_record.rbs +21 -0
  39. data/sig/crystil/wrappers/ruby_llm_response.rbs +39 -0
  40. data/sig/crystil/wrappers/stopped_call.rbs +26 -0
  41. metadata +16 -2
@@ -180,113 +180,101 @@ module Crystil
180
180
 
181
181
  define_method(:post) do |path:, body:|
182
182
  # Non-chat-completions paths pass through untouched — no analytics,
183
- # no sentinel. (At time of writing the gem only ever uses post for
184
- # chat completions, but be defensive about future endpoints.)
183
+ # no sentinel, and outside the `begin` below, so their errors are not recorded either.
184
+ # (The gem only uses post for chat completions, but an app can call it.)
185
185
  return original_post(path: path, body: body) unless path == chat_path
186
186
 
187
- start_time = Time.now
188
- version = defined?(::Groq::VERSION) ? ::Groq::VERSION : nil
189
- title = Crystil::Wrappers::Groq.extract_model_title(body[:model], GROQ_PROVIDER)
190
-
191
- sentinel = instance_variable_get(:@crystil_sentinel)
192
- sentinel&.raise_if_irrelevant!(
193
- title: title,
194
- request: body,
195
- provider: GROQ_PROVIDER,
196
- version: version
197
- )
198
-
199
- # Dup before mutating so the caller's body hash is unchanged.
200
- body = body.dup
201
- streaming = body[:stream_chunk].respond_to?(:call)
202
- accumulated_response = streaming ? {} : nil
203
-
204
- if streaming
205
- # Match the JS/Python behavior: ask Groq to include usage on the
206
- # terminal chunk so the merged response carries token counts.
207
- # A caller-set value (true or false) wins — we only force `true`
208
- # when the key is absent.
209
- body[:stream_options] = { include_usage: true }.merge(body[:stream_options] || {})
210
-
211
- user_callback = body[:stream_chunk]
212
- body[:stream_chunk] = proc do |content, chunk|
213
- if chunk.is_a?(Hash)
214
- normalized = crystil_normalize_openai_chunk(chunk)
215
- crystil_merge_streaming_chunk(accumulated_response, normalized)
187
+ begin
188
+ start_time = Time.now
189
+ version = defined?(::Groq::VERSION) ? ::Groq::VERSION : nil
190
+ title = Crystil::Wrappers::Groq.extract_model_title(body[:model], GROQ_PROVIDER)
191
+
192
+ crystil_raise_if_irrelevant!(
193
+ title: title,
194
+ request: body,
195
+ start_time: start_time,
196
+ provider: GROQ_PROVIDER,
197
+ version: version
198
+ )
199
+ passed_sentinel = true
200
+
201
+ # Dup before mutating so the caller's body hash is unchanged.
202
+ body = body.dup
203
+ streaming = body[:stream_chunk].respond_to?(:call)
204
+ accumulated_response = streaming ? {} : nil
205
+
206
+ if streaming
207
+ # Match the JS/Python behavior: ask Groq to include usage on the
208
+ # terminal chunk so the merged response carries token counts.
209
+ # A caller-set value (true or false) wins — we only force `true`
210
+ # when the key is absent.
211
+ body[:stream_options] = { include_usage: true }.merge(body[:stream_options] || {})
212
+
213
+ user_callback = body[:stream_chunk]
214
+ caller_block = StoppedCall::CallerBlock.new(user_callback)
215
+ body[:stream_chunk] = proc do |content, chunk|
216
+ if chunk.is_a?(Hash)
217
+ normalized = crystil_normalize_openai_chunk(chunk)
218
+ crystil_merge_streaming_chunk(accumulated_response, normalized)
219
+ end
220
+
221
+ # The groq gem's own rule (`Client#to_json_stream`), not `OpenAI.callback_arity`'s,
222
+ # so the callback gets what it would get without Crystil.
223
+ arity = user_callback.is_a?(Proc) ? user_callback.arity : user_callback.method(:call).arity
224
+ if arity == 1
225
+ caller_block.call(content)
226
+ else
227
+ caller_block.call(content, chunk)
228
+ end
216
229
  end
230
+ end
217
231
 
218
- # The gem inspects user_proc.arity to decide between
219
- # call(content) and call(content, chunk); forward with the
220
- # caller's intended signature.
221
- arity = user_callback.is_a?(Proc) ? user_callback.arity : user_callback.method(:call).arity
222
- if arity == 1
223
- user_callback.call(content)
224
- else
225
- user_callback.call(content, chunk)
226
- end
232
+ response = original_post(path: path, body: body)
233
+
234
+ final_response = if streaming
235
+ accumulated_response
236
+ elsif response.respond_to?(:body)
237
+ response.body
238
+ else
239
+ response
240
+ end
241
+
242
+ recorded = true
243
+ crystil_submit_analytics(
244
+ method: :post,
245
+ args: [],
246
+ kwargs: body,
247
+ response: final_response,
248
+ start_time: start_time,
249
+ end_time: Time.now,
250
+ provider: GROQ_PROVIDER,
251
+ title: title,
252
+ version: version
253
+ )
254
+
255
+ response
256
+ rescue SignalException, StandardError => e
257
+ # A block from a nested call falls through: this call reached the provider, so it failed.
258
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
259
+
260
+ error = e
261
+ raise e
262
+ ensure
263
+ # Recorded here, not in the rescue: a `break`, `throw`, timeout or killed thread skips it.
264
+ if !recorded && passed_sentinel
265
+ # A failed stream keeps the chunks merged so far, however it was cut off, so the backend
266
+ # can read the partial content. Non-streaming and pre-chunk failures get `{error, class}`.
267
+ failed_response = Crystil::Wrappers::Groq.build_error_response(
268
+ streaming: streaming, accumulated: accumulated_response,
269
+ error: error || Crystil::StreamError.new(EventStream::STREAM_CUT_SHORT_MESSAGE)
270
+ )
271
+ crystil_submit_unfinished_analytics(
272
+ error, caller_block,
273
+ method: :post, kwargs: body, received: accumulated_response, failed_response: failed_response,
274
+ start_time: start_time, provider: GROQ_PROVIDER, title: title, version: version
275
+ )
227
276
  end
228
277
  end
229
-
230
- response = original_post(path: path, body: body)
231
-
232
- final_response = if streaming
233
- accumulated_response
234
- elsif response.respond_to?(:body)
235
- response.body
236
- else
237
- response
238
- end
239
-
240
- # Sanitize body for analytics: stream_chunk is a Proc and the
241
- # collector would fail to JSON-encode it. Mirror the OpenAI
242
- # wrapper's `:stream` → `true` collapse.
243
- analytics_body = body.dup
244
- analytics_body[:stream_chunk] = true if analytics_body[:stream_chunk].respond_to?(:call)
245
-
246
- crystil_submit_analytics(
247
- method: :post,
248
- args: [],
249
- kwargs: analytics_body,
250
- response: final_response,
251
- start_time: start_time,
252
- end_time: Time.now,
253
- provider: GROQ_PROVIDER,
254
- title: title,
255
- version: version
256
- )
257
-
258
- response
259
- rescue CrystilRequestInterceptedError => e
260
- # We don't want to send intercepts to collector
261
- raise e
262
- rescue StandardError => e
263
- analytics_body = body.dup
264
- analytics_body[:stream_chunk] = true if analytics_body[:stream_chunk].respond_to?(:call)
265
-
266
- # On streaming failure after one or more chunks merged, pass the
267
- # accumulated response (plus error info) through so the backend
268
- # extractor can pull partial assistant content / token usage from
269
- # what was received before the error. Non-streaming and
270
- # pre-chunk failures fall back to the helper's default
271
- # `{error, class}` shape.
272
- error_response = Crystil::Wrappers::Groq.build_error_response(
273
- streaming: streaming, accumulated: accumulated_response, error: e
274
- )
275
-
276
- crystil_submit_error_analytics(
277
- method: :post,
278
- args: [],
279
- kwargs: analytics_body,
280
- error: e,
281
- start_time: start_time,
282
- end_time: Time.now,
283
- provider: GROQ_PROVIDER,
284
- title: title,
285
- version: version,
286
- response: error_response
287
- )
288
-
289
- raise e
290
278
  end
291
279
  end
292
280
  end
@@ -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