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
@@ -6,6 +6,8 @@ module Crystil
6
6
  module Wrappers
7
7
  # Wrapper for Anthropic Ruby client
8
8
  class Anthropic
9
+ REQUEST_OPTIONS_KEYS = [:request_options, "request_options"].freeze
10
+
9
11
  def initialize(config, collector, sentinel = nil)
10
12
  @config = config
11
13
  @collector = collector
@@ -30,6 +32,57 @@ module Crystil
30
32
  client
31
33
  end
32
34
 
35
+ # A copy of the params without `request_options`, whose `extra_headers` can hold credentials.
36
+ # Used for telemetry and sentinel only; the gem still gets the original.
37
+ def self.recorded_params(params)
38
+ return params unless params.is_a?(Hash)
39
+
40
+ params.reject { |key, _| REQUEST_OPTIONS_KEYS.include?(key) }
41
+ end
42
+
43
+ # The query as it went over the wire.
44
+ #
45
+ # The caller never passes `stream:` to `messages.stream` / `stream_raw` —
46
+ # the gem stores it on the parsed params before building the request — so
47
+ # recording it here keeps the payload honest about what was actually sent.
48
+ # Returns a new hash; the caller's is never mutated.
49
+ def self.streamed_query(params)
50
+ return params unless params.is_a?(Hash)
51
+
52
+ params.merge(stream: true)
53
+ end
54
+
55
+ # The enumerable whose events are the ones the API actually sent.
56
+ #
57
+ # `stream_raw` hands back an `Anthropic::Internal::Stream` whose own events
58
+ # are the raw ones, so it is watched directly.
59
+ #
60
+ # `stream` hands back a `MessageStream`, and watching *that* would record
61
+ # the wrong list. Its `each` yields a mix: it adds synthesized `text` /
62
+ # `input_json` / `thinking` events and replaces `content_block_stop` and
63
+ # `message_stop` with richer versions of its own. The backend needs the
64
+ # real `content_block_stop` to parse a tool call's accumulated JSON. Its
65
+ # `@raw_stream` ivar holds the untouched API stream and is read lazily (the
66
+ # iterator is a `chain_fused` Enumerator whose body runs on first
67
+ # iteration), so patching `each` on the object already sitting there is
68
+ # picked up when the caller starts reading.
69
+ #
70
+ # `@raw_stream` is private to the gem, and the gemspec floats across the
71
+ # 1.x line, so a future release could move or rename it. When that inner
72
+ # stream cannot be found, the `stream` path records nothing rather than
73
+ # falling back to the outer object: a streamed payload missing
74
+ # `message_start` makes the backend's extractor raise, so emitting nothing
75
+ # beats emitting a list it cannot read.
76
+ def self.raw_event_stream(stream, method_name)
77
+ return nil unless stream.respond_to?(:each)
78
+ return stream if method_name == :stream_raw
79
+ return nil unless stream.respond_to?(:instance_variable_defined?)
80
+ return nil unless stream.instance_variable_defined?(:@raw_stream)
81
+
82
+ inner = stream.instance_variable_get(:@raw_stream)
83
+ inner if inner.respond_to?(:each)
84
+ end
85
+
33
86
  private
34
87
 
35
88
  def validate_client!(client)
@@ -47,6 +100,17 @@ module Crystil
47
100
  messages_resource.instance_variable_set(:@crystil_collector, client.instance_variable_get(:@crystil_collector))
48
101
  messages_resource.instance_variable_set(:@crystil_sentinel, client.instance_variable_get(:@crystil_sentinel))
49
102
 
103
+ wrap_create_method(messages_resource)
104
+
105
+ # `messages.create(stream: true)` raises ArgumentError in this gem — it
106
+ # routes streaming through its own methods, which bypass `create`
107
+ # entirely. Wrap them only when present, so mocked clients that define
108
+ # just `create` still register.
109
+ wrap_streaming_method(messages_resource, :stream) if messages_resource.respond_to?(:stream)
110
+ wrap_streaming_method(messages_resource, :stream_raw) if messages_resource.respond_to?(:stream_raw)
111
+ end
112
+
113
+ def wrap_create_method(messages_resource)
50
114
  # Store the original create method
51
115
  original_create = messages_resource.method(:create)
52
116
 
@@ -59,13 +123,14 @@ module Crystil
59
123
  version = defined?(::Anthropic::VERSION) ? ::Anthropic::VERSION : nil
60
124
 
61
125
  # Extract parameters for sentinel and analytics
62
- params = kwargs.any? ? kwargs : (args.first || {})
63
- sentinel = instance_variable_get(:@crystil_sentinel)
64
- sentinel&.raise_if_irrelevant!(
126
+ params = Crystil::Wrappers::Anthropic.recorded_params(kwargs.any? ? kwargs : (args.first || {}))
127
+ crystil_raise_if_irrelevant!(
65
128
  title: ANTHROPIC_CLIENT_TITLE,
66
129
  request: params,
130
+ start_time: start_time,
67
131
  version: version
68
132
  )
133
+ passed_sentinel = true
69
134
 
70
135
  # Call original method
71
136
  response = if kwargs.any?
@@ -75,6 +140,7 @@ module Crystil
75
140
  end
76
141
 
77
142
  # Submit analytics
143
+ recorded = true
78
144
  crystil_submit_analytics(
79
145
  method: :create,
80
146
  args: args,
@@ -87,24 +153,95 @@ module Crystil
87
153
  )
88
154
 
89
155
  response
90
- rescue CrystilRequestInterceptedError => e
91
- # We don't want to send intercepts to collector
156
+ rescue SignalException, StandardError => e
157
+ # Recorded as blocked where Sentinel answers (crystil_raise_if_irrelevant!), never as a failure.
158
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
159
+
160
+ error = e
92
161
  raise e
93
- rescue StandardError => e
94
- params = kwargs.any? ? kwargs : (args.first || {})
162
+ ensure
163
+ # Recorded here, not in the rescue: a timeout or a killed thread skips the rescue.
164
+ # A signal is recorded as stopped, anything else as failed; a call that never passed Sentinel is not.
165
+ if !recorded && passed_sentinel
166
+ crystil_submit_unfinished_analytics(
167
+ error, nil,
168
+ method: :create, kwargs: params, start_time: start_time, title: ANTHROPIC_CLIENT_TITLE, version: version
169
+ )
170
+ end
171
+ end
172
+ end
95
173
 
96
- crystil_submit_error_analytics(
97
- method: :create,
98
- args: args,
99
- kwargs: params,
100
- error: e,
101
- start_time: start_time,
102
- end_time: Time.now,
174
+ # Wraps `messages.stream` / `messages.stream_raw`.
175
+ #
176
+ # Both return a lazy stream, so there is nothing to record when the method
177
+ # returns — the payload is the events, and none have arrived yet. The
178
+ # response is instead recorded once the caller has read the stream, as the
179
+ # unmerged event list the backend's streamed Anthropic extractor expects.
180
+ # See `Base#crystil_record_event_stream`.
181
+ def wrap_streaming_method(messages_resource, method_name)
182
+ original_method = messages_resource.method(method_name)
183
+
184
+ messages_resource.define_singleton_method(method_name) do |*args, **kwargs, &block|
185
+ # Include Base module methods
186
+ extend Base unless singleton_class.include?(Base)
187
+
188
+ start_time = Time.now
189
+ version = defined?(::Anthropic::VERSION) ? ::Anthropic::VERSION : nil
190
+
191
+ # Extract parameters for sentinel and analytics
192
+ params = Crystil::Wrappers::Anthropic.recorded_params(kwargs.any? ? kwargs : (args.first || {}))
193
+ crystil_raise_if_irrelevant!(
103
194
  title: ANTHROPIC_CLIENT_TITLE,
195
+ request: params,
196
+ query: Crystil::Wrappers::Anthropic.streamed_query(params),
197
+ start_time: start_time,
104
198
  version: version
105
199
  )
200
+ passed_sentinel = true
106
201
 
202
+ # Call original method
203
+ stream = if kwargs.any?
204
+ original_method.call(**kwargs, &block)
205
+ else
206
+ original_method.call(*args, &block)
207
+ end
208
+
209
+ events = Crystil::Wrappers::Anthropic.raw_event_stream(stream, method_name)
210
+
211
+ if events
212
+ crystil_record_event_stream(
213
+ events,
214
+ closer: stream,
215
+ method: method_name,
216
+ # Copied now, not at report time, so changes the caller makes while reading don't leak in.
217
+ kwargs: deep_copy(Crystil::Wrappers::Anthropic.streamed_query(params)),
218
+ start_time: start_time,
219
+ title: ANTHROPIC_CLIENT_TITLE,
220
+ version: version
221
+ )
222
+ end
223
+
224
+ # From here the stream's reads and `close` report the call.
225
+ recorded = true
226
+ # The caller's own object, so `accumulated_message`, `text`,
227
+ # `until_done` and the rest of its surface keep working.
228
+ stream
229
+ rescue SignalException, StandardError => e
230
+ # Recorded as blocked where Sentinel answers (crystil_raise_if_irrelevant!), never as a failure.
231
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
232
+
233
+ error = e
107
234
  raise e
235
+ ensure
236
+ # Recorded here, not in the rescue: a timeout or a killed thread skips the rescue.
237
+ # A signal is recorded as stopped, anything else as failed; a call that never passed Sentinel is not.
238
+ if !recorded && passed_sentinel
239
+ crystil_submit_unfinished_analytics(
240
+ error, nil,
241
+ method: method_name, kwargs: Crystil::Wrappers::Anthropic.streamed_query(params),
242
+ start_time: start_time, title: ANTHROPIC_CLIENT_TITLE, version: version
243
+ )
244
+ end
108
245
  end
109
246
  end
110
247
  end
@@ -2,10 +2,20 @@
2
2
 
3
3
  require "time"
4
4
 
5
+ require_relative "blocked_call"
6
+ require_relative "deep_copy"
7
+ require_relative "event_stream"
8
+ require_relative "stopped_call"
9
+
5
10
  module Crystil
6
11
  module Wrappers
7
12
  # Base functionality for all provider wrappers
8
13
  module Base
14
+ include BlockedCall
15
+ include DeepCopy
16
+ include EventStream
17
+ include StoppedCall
18
+
9
19
  def crystil_wrap_method(method_name, _provider_name)
10
20
  return if method(method_name).source_location&.first&.include?("crystil")
11
21
 
@@ -45,7 +55,7 @@ module Crystil
45
55
 
46
56
  def crystil_submit_analytics(method:, args:, kwargs:, response:, start_time:,
47
57
  end_time:, provider: nil, title: nil, version: nil,
48
- status: "succeeded", exception: nil)
58
+ status: "succeeded", exception: nil, reason: nil)
49
59
  collector = instance_variable_get(:@crystil_collector)
50
60
  config = instance_variable_get(:@crystil_config)
51
61
 
@@ -61,7 +71,8 @@ module Crystil
61
71
  provider: provider,
62
72
  title: title,
63
73
  version: version,
64
- exception: exception
74
+ exception: exception,
75
+ reason: reason
65
76
  )
66
77
 
67
78
  collector.submit_async(payload)
@@ -110,11 +121,13 @@ module Crystil
110
121
  accumulated
111
122
  end
112
123
 
124
+ # Returns a copy of the chunk with every delta holding all of its keys, nil
125
+ # when missing, as the Python SDK sends them. A copy, so the chunk the app's
126
+ # callback gets is the gem's own, and the merge can keep it.
113
127
  def crystil_normalize_openai_chunk(chunk)
114
- # Normalize OpenAI streaming chunks to match Python SDK format
115
- # Ensure delta objects have all keys present with null values
116
128
  return chunk unless chunk.is_a?(Hash)
117
129
 
130
+ chunk = deep_copy(chunk)
118
131
  if chunk["choices"].is_a?(Array)
119
132
  chunk["choices"].each do |choice|
120
133
  next unless choice.is_a?(Hash) && choice.key?("delta")
@@ -137,20 +150,17 @@ module Crystil
137
150
  private
138
151
 
139
152
  def extract_query(_method, _args, kwargs)
140
- # Deep copy to avoid mutation issues
141
- query = deep_copy(kwargs)
142
-
143
- # Normalize stream parameter: convert Proc to boolean true
144
- # This ensures streaming requests are properly serialized to JSON
145
- query[:stream] = true if query.is_a?(Hash) && query[:stream].is_a?(Proc)
146
-
147
- query
153
+ # Callbacks become `true` first: they cannot be sent as JSON, and Marshal
154
+ # cannot copy them, so the deep copy would fall back to a shallow `dup`.
155
+ deep_copy(Crystil::Callables.replace_with_true(kwargs))
148
156
  rescue StandardError
149
157
  {}
150
158
  end
151
159
 
152
160
  def extract_response(response)
153
161
  case response
162
+ when nil
163
+ nil
154
164
  when Hash, Array
155
165
  deep_copy(response)
156
166
  when String
@@ -201,16 +211,6 @@ module Crystil
201
211
  end
202
212
  end
203
213
 
204
- def deep_copy(obj)
205
- Marshal.load(Marshal.dump(obj))
206
- rescue StandardError
207
- begin
208
- obj.dup
209
- rescue StandardError
210
- obj
211
- end
212
- end
213
-
214
214
  # Build the payload that is sent to the collector API which then sends the payload
215
215
  # to the backend.
216
216
  # - conversion.client - Routes the payload to the correct service
@@ -218,9 +218,13 @@ module Crystil
218
218
  # openai, and anthropic) are common title values.
219
219
  # - conversion.query - Holds the request information.
220
220
  # - conversion.response - Holds the response from the LLM. This is different for each LLM,
221
- # and the different services handle them on the backend.
221
+ # and the different services handle them on the backend. `nil` only for a blocked call.
222
+ # - meta.fnfg.reason - Sentinel's reason, sent only for a blocked call.
222
223
  def build_payload(query:, response:, start_time:, end_time:, config:, status:,
223
- provider: nil, title: nil, version: nil, exception: nil)
224
+ provider: nil, title: nil, version: nil, exception: nil, reason: nil)
225
+ fnfg = { status: status, exc: exception }
226
+ fnfg[:reason] = reason if reason
227
+
224
228
  {
225
229
  attribution: config.attribution&.to_h,
226
230
  conversation: {
@@ -236,10 +240,7 @@ module Crystil
236
240
  api: {
237
241
  key: config.api_key
238
242
  },
239
- fnfg: {
240
- status: status,
241
- exc: exception
242
- },
243
+ fnfg: fnfg,
243
244
  sdk: {
244
245
  client: "ruby",
245
246
  version: config.version
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Crystil
4
+ module Wrappers
5
+ # The Sentinel check every wrapper runs before the provider call, and the
6
+ # record it sends when Sentinel blocks that call.
7
+ #
8
+ # Mixed into `Base`, like `EventStream`, so a wrapper reaches it the same
9
+ # way it reaches `crystil_submit_analytics`.
10
+ module BlockedCall
11
+ # Asks Sentinel whether the call may go ahead. A blocked call is still
12
+ # recorded, with no response, before the block is raised.
13
+ #
14
+ # `query` is what the payload records, when it differs from the `request`
15
+ # Sentinel judges. The payload is sent here, not from the wrapper's outer
16
+ # rescue: that also catches a block from a nested call (a RubyLLM tool
17
+ # calling another registered client), and the outer call was not blocked.
18
+ def crystil_raise_if_irrelevant!(request:, start_time:, title:, provider: nil, version: nil, query: request)
19
+ sentinel = instance_variable_get(:@crystil_sentinel)
20
+ sentinel&.raise_if_irrelevant!(title: title, request: request, provider: provider, version: version)
21
+ rescue CrystilRequestInterceptedError => e
22
+ crystil_submit_blocked_analytics(
23
+ query: query, reason: e.message, start_time: start_time,
24
+ provider: provider, title: title, version: version
25
+ )
26
+ raise e
27
+ end
28
+
29
+ # True when `error` is the block this call's own Sentinel check raised, already
30
+ # recorded above. A block from a nested call made after the check passed is
31
+ # false: this call reached the provider, so the wrapper records it as failed.
32
+ def crystil_block_already_recorded?(error, passed_sentinel)
33
+ error.is_a?(CrystilRequestInterceptedError) && !passed_sentinel
34
+ end
35
+
36
+ private
37
+
38
+ # Sends the payload for a call Sentinel blocked: no response, and Sentinel's
39
+ # reason. A failure here must never replace the block, so it is reported and swallowed.
40
+ def crystil_submit_blocked_analytics(query:, reason:, start_time:, provider:, title:, version:)
41
+ crystil_submit_analytics(
42
+ method: :crystil_raise_if_irrelevant!, args: [], kwargs: query, response: nil,
43
+ start_time: start_time, end_time: Time.now,
44
+ provider: provider, title: title, version: version,
45
+ status: "blocked", reason: reason
46
+ )
47
+ rescue StandardError => e
48
+ warn "Crystil: Failed to record blocked call: #{e.message}"
49
+ end
50
+ end
51
+ end
52
+ end
@@ -8,5 +8,8 @@ module Crystil
8
8
  GOOGLE_CLIENT_TITLE = "google"
9
9
  RUBY_LLM_PROVIDER = "ruby_llm"
10
10
  GROQ_PROVIDER = "groq"
11
+
12
+ # The RubyLLM providers that send Gemini's request format: Vertex AI's subclasses Gemini's.
13
+ RUBY_LLM_GEMINI_PROVIDERS = %w[gemini vertexai].freeze
11
14
  end
12
15
  end
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Crystil
4
+ module Wrappers
5
+ # The copy a recorded query or response is taken as. Mixed into `Base`, like
6
+ # `BlockedCall`, so a wrapper reaches `deep_copy` the same way it always has.
7
+ module DeepCopy
8
+ private
9
+
10
+ # A deep copy, taken before the payload is queued, so a change the app makes later
11
+ # cannot reach what is sent. A frozen String is shared, not copied: it cannot change,
12
+ # and a recorded attachment's base64 can run to megabytes. `copies` gives an object
13
+ # held twice, or a structure that holds itself, the same shape in the copy.
14
+ def deep_copy(obj, copies = {}.compare_by_identity)
15
+ case obj
16
+ when Integer, Float, Symbol, nil, true, false
17
+ obj # nothing can change these
18
+ else
19
+ if obj.instance_of?(String)
20
+ obj.frozen? ? obj : obj.dup
21
+ elsif obj.instance_of?(Hash) || obj.instance_of?(Array)
22
+ copies.key?(obj) ? copies[obj] : crystil_copy_container(obj, copies)
23
+ else
24
+ crystil_marshal_copy(obj)
25
+ end
26
+ end
27
+ end
28
+
29
+ def crystil_copy_container(obj, copies)
30
+ if obj.instance_of?(Hash)
31
+ copy = copies[obj] = {}
32
+ obj.each { |key, value| copy[deep_copy(key, copies)] = deep_copy(value, copies) }
33
+ else
34
+ copy = copies[obj] = []
35
+ obj.each { |value| copy << deep_copy(value, copies) }
36
+ end
37
+ copy
38
+ end
39
+
40
+ # Any other object is copied through Marshal, or with `dup` when it cannot be marshaled.
41
+ def crystil_marshal_copy(obj)
42
+ Marshal.load(Marshal.dump(obj))
43
+ rescue StandardError
44
+ begin
45
+ obj.dup
46
+ rescue StandardError
47
+ obj
48
+ end
49
+ end
50
+ end
51
+ end
52
+ end
@@ -0,0 +1,200 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fiber"
4
+ require "json"
5
+
6
+ module Crystil
7
+ module Wrappers
8
+ # Recording a lazy event stream as the list of events the provider sent.
9
+ #
10
+ # Mixed into `Base`, so a wrapper reaches it the same way it reaches
11
+ # `crystil_merge_streaming_chunk`. The two are alternatives, picked by what
12
+ # the backend extractor for that provider reads: merge the chunks into one
13
+ # object for OpenAI and Groq, record the events as a list for Anthropic.
14
+ module EventStream
15
+ STREAM_CUT_SHORT_MESSAGE = "Stream read ended before the provider finished sending events"
16
+
17
+ # Record a lazy event stream as the unmerged list of events the provider
18
+ # sent, once the caller has finished reading it.
19
+ #
20
+ # This is the counterpart to `crystil_merge_streaming_chunk` for providers
21
+ # whose backend extractor reads a *list*. Anthropic is one: its streamed
22
+ # extractor keys off `conversation.response` being a list and takes the
23
+ # model off `message_start`. Merging the events first would flatten them
24
+ # into an object with no top-level model, which the backend cannot read.
25
+ #
26
+ # The stream object is returned as-is with only its `each` replaced, so
27
+ # everything else the provider hung on it keeps working. Enumerable
28
+ # methods (`map`, `to_a`, `first`, ...) route through `each` and are
29
+ # recorded too; `to_enum` reads past it, so a caller using that gets an
30
+ # untraced call rather than a broken one.
31
+ #
32
+ # Analytics fire once per stream however many times it is iterated, and
33
+ # only after the read ends — never per event.
34
+ # `closer` is the caller's object (Anthropic's `MessageStream`, not `@raw_stream`); its `close` reports too,
35
+ # since the call is billed before any read.
36
+ def crystil_record_event_stream(stream, method:, kwargs:, start_time:, title: nil, version: nil, closer: stream)
37
+ return stream unless stream.respond_to?(:each)
38
+
39
+ original_each = stream.method(:each)
40
+ # Per stream, not per read, so a `close` after a partial read that never
41
+ # reached its `ensure` (external iteration via `next`) still has them.
42
+ events = []
43
+ reading_fibers = []
44
+ reported = false
45
+ claim_report = -> { reported ? false : (reported = true) }
46
+ recorder = self
47
+ report = lambda do |finished:, error: nil, caller_block: nil, stopped: nil|
48
+ recorder.crystil_report_event_stream(
49
+ events: events.dup, finished: finished, error: error, caller_block: caller_block, stopped: stopped,
50
+ method: method, kwargs: kwargs, start_time: start_time, title: title, version: version
51
+ )
52
+ end
53
+
54
+ stream.define_singleton_method(:each) do |*args, &block|
55
+ next original_each.call(*args, &block) if block.nil?
56
+
57
+ error = nil
58
+ finished = false
59
+ caller_block = Crystil::Wrappers::StoppedCall::CallerBlock.new(block)
60
+ reading_fibers << Fiber.current
61
+
62
+ begin
63
+ result = original_each.call(*args) do |event|
64
+ events << Crystil::Wrappers::EventStream.crystil_event_to_data(event)
65
+ caller_block.call(event)
66
+ end
67
+ finished = true
68
+ result
69
+ rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised; an Interrupt is recorded too
70
+ error = e
71
+ raise e
72
+ ensure
73
+ reading_fibers.delete_at(reading_fibers.rindex(Fiber.current) || reading_fibers.size)
74
+ # `ensure`, not the end of the `begin` body: `break` and every
75
+ # Enumerable method built on it (`first`, `take`, `find`, `any?`)
76
+ # unwind past both the success path and the `rescue`. Reporting
77
+ # there would leave a caller who stops early — a cancel button, a
78
+ # timeout guard — with a billed call and no record of it, which is
79
+ # the exact failure this recorder exists to prevent.
80
+ report.call(finished: finished, error: error, caller_block: caller_block) if claim_report.call
81
+ end
82
+ end
83
+
84
+ crystil_route_enumerators(stream)
85
+ # The app closing the stream before reading it to the end is a stop, with whatever was read.
86
+ crystil_report_on_close(closer, reading_fibers, claim_report) do
87
+ report.call(finished: false, stopped: true)
88
+ end
89
+
90
+ stream
91
+ rescue StandardError
92
+ # Instrumentation must never be the reason a call fails. A stream that
93
+ # cannot take a singleton method (frozen, or with `each` defined
94
+ # somewhere we cannot reach) simply goes unrecorded, the same fail-open
95
+ # stance sentinel and `extract_response` take.
96
+ stream
97
+ end
98
+
99
+ # Anthropic's `Internal::Stream#to_enum` hands out its inner iterator, skipping the patched `each`.
100
+ # Route it back through so `next`-driven reads are recorded too.
101
+ def crystil_route_enumerators(stream)
102
+ %i[to_enum enum_for].each do |name|
103
+ stream.define_singleton_method(name) do |meth = :each, *args, &blk|
104
+ ::Kernel.instance_method(:to_enum).bind(self).call(meth, *args, &blk)
105
+ end
106
+ end
107
+ end
108
+
109
+ # Wrap `close` so it reports when no read has. A `close` from inside the
110
+ # caller's own read loop is left to that read's `ensure`, which sees the whole read.
111
+ def crystil_report_on_close(closer, reading_fibers, claim_report, &report)
112
+ return unless closer.respond_to?(:close)
113
+
114
+ original_close = closer.method(:close)
115
+ closer.define_singleton_method(:close) do |*args, &block|
116
+ original_close.call(*args, &block)
117
+ ensure
118
+ report.call if !reading_fibers.include?(Fiber.current) && claim_report.call
119
+ end
120
+ end
121
+
122
+ # Submit the one payload for a finished read.
123
+ #
124
+ # The events captured are what the provider actually sent, and what it
125
+ # billed for, so they are kept even when the read ended early or badly —
126
+ # a stream cut off by a network drop still tells us the input tokens. An
127
+ # Anthropic event list always opens with `message_start`, so any non-empty
128
+ # capture is one the backend extractor can read; an empty one is not, and
129
+ # falls back to the plain error shape, or to sending nothing at all.
130
+ #
131
+ # A read that did not finish is `stopped` when the app ended it (see
132
+ # `StoppedCall`) and `failed` otherwise; `stopped` says so outright for a `close`.
133
+ def crystil_report_event_stream(events:, finished:, error:, caller_block:, method:, kwargs:, start_time:,
134
+ stopped: nil, title: nil, version: nil)
135
+ response = events.empty? ? nil : events
136
+
137
+ if !finished
138
+ crystil_submit_unfinished_analytics(
139
+ error, caller_block,
140
+ method: method, kwargs: kwargs, start_time: start_time, title: title, version: version,
141
+ received: response, failed_response: response, stopped: stopped
142
+ )
143
+ elsif response
144
+ crystil_submit_analytics(
145
+ method: method, args: [], kwargs: kwargs, response: response,
146
+ start_time: start_time, end_time: Time.now, title: title, version: version
147
+ )
148
+ end
149
+ rescue StandardError => e
150
+ # This runs from the recorder's `ensure`, so anything raised here would
151
+ # escape the caller's `each` — failing a call that succeeded, or
152
+ # replacing the provider's own error with ours. Reporting is best-effort.
153
+ warn "Crystil: Failed to record stream analytics: #{e.message}"
154
+ end
155
+
156
+ # A streamed event as plain data, captured the moment it goes past.
157
+ #
158
+ # Converting here rather than at submission time is deliberate. Anthropic's
159
+ # `MessageStream` accumulates into the events' own nested objects as later
160
+ # ones arrive — `message_start`'s `message`, and each `content_block_start`'s
161
+ # `content_block` — so a reference held until the stream ends would report
162
+ # the final snapshot as though the opening events had carried it.
163
+ # `extract_response` also deep-copies an Array as-is, so provider objects
164
+ # left in the list would reach the collector unserialized.
165
+ #
166
+ # Provider event models have a shallow `to_h`; their `deep_to_h` is a real copy. Objects without
167
+ # one are copied through a JSON round trip, and plain Hash/Array events through Marshal.
168
+ def self.crystil_event_to_data(event)
169
+ return event if event.nil?
170
+ return crystil_deep_copy(event) if event.is_a?(Hash) || event.is_a?(Array)
171
+ return event.deep_to_h if event.respond_to?(:deep_to_h)
172
+
173
+ data = JSON.parse(JSON.generate(event))
174
+
175
+ # `JSON.generate` does not raise on an object with no JSON-aware
176
+ # `to_json`: `Object#to_json` emits the object's `to_s`, which parses
177
+ # back as a String. Anything but a Hash or Array means the round trip
178
+ # produced an inspect string rather than the event's data.
179
+ return data if data.is_a?(Hash) || data.is_a?(Array)
180
+
181
+ crystil_event_to_hash(event)
182
+ rescue StandardError
183
+ crystil_event_to_hash(event)
184
+ end
185
+
186
+ def self.crystil_event_to_hash(event)
187
+ event.respond_to?(:to_h) ? event.to_h : event
188
+ rescue StandardError
189
+ event
190
+ end
191
+
192
+ # Plain data that cannot be marshaled (a Proc inside, say) is kept as-is rather than dropped.
193
+ def self.crystil_deep_copy(data)
194
+ Marshal.load(Marshal.dump(data))
195
+ rescue StandardError
196
+ data
197
+ end
198
+ end
199
+ end
200
+ end