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
@@ -4,8 +4,14 @@ require_relative "constants"
4
4
 
5
5
  module Crystil
6
6
  module Wrappers
7
- # Wrapper for Google GenerativeAI Ruby client (gemini-ai gem version 4.3.0)
7
+ # Wrapper for the Google GenerativeAI Ruby client (gemini-ai gem v4.3.0).
8
+ # Alone among the wrappers, the recorded query carries a field the caller
9
+ # never sent — see `extract_model`.
8
10
  class GeminiAI
11
+ # Shape of the gem's `@model_address`. Anchored at the end so a path a
12
+ # future version builds differently reads as unknown, not as a wrong model.
13
+ MODEL_ADDRESS_PATTERN = %r{(?:\A|/)models/(?<model>[^/]+)\z}.freeze
14
+
9
15
  def initialize(config, collector, sentinel = nil)
10
16
  @config = config
11
17
  @collector = collector
@@ -31,6 +37,35 @@ module Crystil
31
37
  client
32
38
  end
33
39
 
40
+ # The model this client is pinned to, or nil if unreadable. The gem keeps
41
+ # it on the client, so a failed call names the model nowhere else.
42
+ def self.extract_model(client)
43
+ address = client.instance_variable_get(:@model_address)
44
+ return nil unless address.is_a?(String)
45
+
46
+ address[MODEL_ADDRESS_PATTERN, :model]
47
+ end
48
+
49
+ # A copy of the caller's parameters with the client's model filled in, for
50
+ # recording only. Their own model wins; their hash is never mutated.
51
+ def self.parameters_with_model(parameters, model)
52
+ return parameters unless parameters.is_a?(Hash) && model
53
+ return parameters if parameters.key?(:model) || parameters.key?("model")
54
+
55
+ parameters.merge(model: model)
56
+ end
57
+
58
+ # The block the gem calls with each streamed event: it keeps the event, then
59
+ # calls the app's block, so a stream the app stops is recorded with what arrived.
60
+ def self.watched_block(caller_block, received)
61
+ return nil if caller_block.nil?
62
+
63
+ proc do |event, *rest|
64
+ received << event
65
+ caller_block.call(event, *rest)
66
+ end
67
+ end
68
+
34
69
  private
35
70
 
36
71
  def validate_client!(client)
@@ -60,21 +95,33 @@ module Crystil
60
95
  start_time = Time.now
61
96
  version = defined?(::Gemini::GEM) && ::Gemini::GEM.is_a?(Hash) ? ::Gemini::GEM[:version] : nil
62
97
 
63
- sentinel = instance_variable_get(:@crystil_sentinel)
64
- sentinel&.raise_if_irrelevant!(
98
+ # The gem pins the model to the client rather than the request, so
99
+ # record it alongside the caller's parameters — a failed call has no
100
+ # response to read it from. See GeminiAI.extract_model.
101
+ model = Crystil::Wrappers::GeminiAI.extract_model(self)
102
+ recorded_query = Crystil::Wrappers::GeminiAI.parameters_with_model(parameters, model)
103
+
104
+ crystil_raise_if_irrelevant!(
65
105
  title: GOOGLE_CLIENT_TITLE,
66
- request: parameters,
106
+ request: recorded_query,
107
+ start_time: start_time,
67
108
  version: version
68
109
  )
110
+ passed_sentinel = true
69
111
 
70
- # Call original method
71
- response = original_generate_content(*args, **kwargs, &block)
112
+ # A block makes the gem stream. It is wrapped to keep each event, so a stop is recorded with them.
113
+ received = []
114
+ caller_block = block && StoppedCall::CallerBlock.new(block)
115
+ response = original_generate_content(
116
+ *args, **kwargs, &Crystil::Wrappers::GeminiAI.watched_block(caller_block, received)
117
+ )
72
118
 
73
119
  # Submit analytics
120
+ recorded = true
74
121
  crystil_submit_analytics(
75
122
  method: :generate_content,
76
123
  args: [],
77
- kwargs: parameters,
124
+ kwargs: recorded_query,
78
125
  response: response,
79
126
  start_time: start_time,
80
127
  end_time: Time.now,
@@ -83,22 +130,21 @@ module Crystil
83
130
  )
84
131
 
85
132
  response
86
- rescue CrystilRequestInterceptedError => e
87
- # We don't want to send intercepts to collector
88
- raise e
89
- rescue StandardError => e
90
- crystil_submit_error_analytics(
91
- method: :generate_content,
92
- args: [],
93
- kwargs: parameters,
94
- error: e,
95
- start_time: start_time,
96
- end_time: Time.now,
97
- title: GOOGLE_CLIENT_TITLE,
98
- version: version
99
- )
133
+ rescue SignalException, StandardError => e
134
+ # A block from a nested call falls through: this call reached the provider, so it failed.
135
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
100
136
 
137
+ error = e
101
138
  raise e
139
+ ensure
140
+ # Recorded here, not in the rescue: a `break` or `throw` from the app's block raises nothing.
141
+ if !recorded && passed_sentinel
142
+ crystil_submit_unfinished_analytics(
143
+ error, caller_block,
144
+ method: :generate_content, kwargs: recorded_query, received: received,
145
+ start_time: start_time, title: GOOGLE_CLIENT_TITLE, version: version
146
+ )
147
+ end
102
148
  end
103
149
  end
104
150
  end
@@ -126,21 +172,33 @@ module Crystil
126
172
  start_time = Time.now
127
173
  version = defined?(::Gemini::GEM) && ::Gemini::GEM.is_a?(Hash) ? ::Gemini::GEM[:version] : nil
128
174
 
129
- sentinel = instance_variable_get(:@crystil_sentinel)
130
- sentinel&.raise_if_irrelevant!(
175
+ # The gem pins the model to the client rather than the request, so
176
+ # record it alongside the caller's parameters — a failed call has no
177
+ # response to read it from. See GeminiAI.extract_model.
178
+ model = Crystil::Wrappers::GeminiAI.extract_model(self)
179
+ recorded_query = Crystil::Wrappers::GeminiAI.parameters_with_model(parameters, model)
180
+
181
+ crystil_raise_if_irrelevant!(
131
182
  title: GOOGLE_CLIENT_TITLE,
132
- request: parameters,
183
+ request: recorded_query,
184
+ start_time: start_time,
133
185
  version: version
134
186
  )
187
+ passed_sentinel = true
135
188
 
136
- # Call original method with wrapped block
137
- response = original_stream_generate_content(*args, **kwargs, &block)
189
+ # A block makes the gem stream. It is wrapped to keep each event, so a stop is recorded with them.
190
+ received = []
191
+ caller_block = block && StoppedCall::CallerBlock.new(block)
192
+ response = original_stream_generate_content(
193
+ *args, **kwargs, &Crystil::Wrappers::GeminiAI.watched_block(caller_block, received)
194
+ )
138
195
 
139
196
  # Submit analytics with accumulated response
197
+ recorded = true
140
198
  crystil_submit_analytics(
141
199
  method: :stream_generate_content,
142
200
  args: [],
143
- kwargs: parameters,
201
+ kwargs: recorded_query,
144
202
  response: response,
145
203
  start_time: start_time,
146
204
  end_time: Time.now,
@@ -149,22 +207,21 @@ module Crystil
149
207
  )
150
208
 
151
209
  response
152
- rescue CrystilRequestInterceptedError => e
153
- # We don't want to send intercepts to collector
154
- raise e
155
- rescue StandardError => e
156
- crystil_submit_error_analytics(
157
- method: :stream_generate_content,
158
- args: [],
159
- kwargs: parameters,
160
- error: e,
161
- start_time: start_time,
162
- end_time: Time.now,
163
- title: GOOGLE_CLIENT_TITLE,
164
- version: version
165
- )
210
+ rescue SignalException, StandardError => e
211
+ # A block from a nested call falls through: this call reached the provider, so it failed.
212
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
166
213
 
214
+ error = e
167
215
  raise e
216
+ ensure
217
+ # Recorded here, not in the rescue: a `break` or `throw` from the app's block raises nothing.
218
+ if !recorded && passed_sentinel
219
+ crystil_submit_unfinished_analytics(
220
+ error, caller_block,
221
+ method: :stream_generate_content, kwargs: recorded_query, received: received,
222
+ start_time: start_time, title: GOOGLE_CLIENT_TITLE, version: version
223
+ )
224
+ end
168
225
  end
169
226
  end
170
227
  end
@@ -81,12 +81,13 @@ module Crystil
81
81
  # Extract parameters for analytics
82
82
  params = kwargs.any? ? kwargs : (args.first || {})
83
83
 
84
- sentinel = instance_variable_get(:@crystil_sentinel)
85
- sentinel&.raise_if_irrelevant!(
84
+ crystil_raise_if_irrelevant!(
86
85
  title: GOOGLE_CLIENT_TITLE,
87
86
  request: params,
87
+ start_time: start_time,
88
88
  version: version
89
89
  )
90
+ passed_sentinel = true
90
91
 
91
92
  # Call original method
92
93
  response = if kwargs.any?
@@ -96,6 +97,7 @@ module Crystil
96
97
  end
97
98
 
98
99
  # Submit analytics
100
+ recorded = true
99
101
  crystil_submit_analytics(
100
102
  method: :generate_content,
101
103
  args: args,
@@ -108,24 +110,22 @@ module Crystil
108
110
  )
109
111
 
110
112
  response
111
- rescue CrystilRequestInterceptedError => e
112
- # We don't want to send intercepts to collector
113
- raise e
114
- rescue StandardError => e
115
- params = kwargs.any? ? kwargs : (args.first || {})
116
-
117
- crystil_submit_error_analytics(
118
- method: :generate_content,
119
- args: args,
120
- kwargs: params,
121
- error: e,
122
- start_time: start_time,
123
- end_time: Time.now,
124
- title: GOOGLE_CLIENT_TITLE,
125
- version: version
126
- )
113
+ rescue SignalException, StandardError => e
114
+ # Recorded as blocked where Sentinel answers (crystil_raise_if_irrelevant!), never as a failure.
115
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
127
116
 
117
+ error = e
128
118
  raise e
119
+ ensure
120
+ # Recorded here, not in the rescue: a timeout or a killed thread skips the rescue.
121
+ # A signal is recorded as stopped, anything else as failed; a call that never passed Sentinel is not.
122
+ if !recorded && passed_sentinel
123
+ crystil_submit_unfinished_analytics(
124
+ error, nil,
125
+ method: :generate_content, kwargs: params,
126
+ start_time: start_time, title: GOOGLE_CLIENT_TITLE, version: version
127
+ )
128
+ end
129
129
  end
130
130
  end
131
131
  end
@@ -10,10 +10,10 @@ module Crystil
10
10
  # OpenAI gpt-oss, Qwen, compound systems), so it sits in
11
11
  # `conversation.client.provider = "groq"` rather than `title`. `title` is
12
12
  # derived per-call from the model-ID prefix — e.g.
13
- # `meta-llama/llama-4-scout-17b-16e-instruct` → `"meta-llama"`,
14
- # `openai/gpt-oss-20b` → `"openai"`. Legacy un-prefixed IDs
15
- # (`llama-3.1-8b-instant`, `allam-2-7b`) fall back to the first
16
- # alphanumeric run (`"llama"`, `"allam"`); anything unparseable falls
13
+ # `meta-llama/llama-prompt-guard-2-86m` → `"meta-llama"`,
14
+ # `openai/gpt-oss-20b` → `"openai"`. Un-prefixed IDs
15
+ # (`allam-2-7b`, `whisper-large-v3`) fall back to the first
16
+ # alphanumeric run (`"allam"`, `"whisper"`); anything unparseable falls
17
17
  # back to `GROQ_PROVIDER` (`"groq"`). `title` is never nil.
18
18
  #
19
19
  # Unlike the JS / Python groq-sdk, the Ruby `groq` gem's `Client#chat`
@@ -65,10 +65,10 @@ module Crystil
65
65
  #
66
66
  # Rules:
67
67
  # - String with `/`: return everything before the first `/`
68
- # (`meta-llama/llama-4-...` → `"meta-llama"`, `openai/gpt-oss-20b`
69
- # → `"openai"`).
68
+ # (`meta-llama/llama-prompt-guard-2-86m` → `"meta-llama"`,
69
+ # `openai/gpt-oss-20b` → `"openai"`).
70
70
  # - String without `/`: return the first run of alphanumeric characters
71
- # (`llama-3.1-8b-instant` → `"llama"`, `allam-2-7b` → `"allam"`,
71
+ # (`allam-2-7b` → `"allam"`, `whisper-large-v3` → `"whisper"`,
72
72
  # `gpt-4o` → `"gpt"`).
73
73
  # - Anything else (non-string, empty, unrecognized shape): return
74
74
  # `fallback`.
@@ -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