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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +115 -42
- data/LICENSE +1 -1
- data/README.md +11 -3
- data/lib/crystil/callables.rb +24 -0
- data/lib/crystil/client.rb +7 -0
- data/lib/crystil/collector.rb +127 -4
- data/lib/crystil/sentinel.rb +2 -19
- data/lib/crystil/version.rb +1 -1
- data/lib/crystil/wrappers/anthropic.rb +151 -14
- data/lib/crystil/wrappers/base.rb +29 -28
- data/lib/crystil/wrappers/blocked_call.rb +52 -0
- data/lib/crystil/wrappers/constants.rb +3 -0
- data/lib/crystil/wrappers/deep_copy.rb +52 -0
- data/lib/crystil/wrappers/event_stream.rb +200 -0
- data/lib/crystil/wrappers/geminiai.rb +98 -41
- data/lib/crystil/wrappers/google.rb +18 -18
- data/lib/crystil/wrappers/groq.rb +96 -108
- data/lib/crystil/wrappers/openai.rb +118 -101
- data/lib/crystil/wrappers/ruby_llm.rb +150 -101
- data/lib/crystil/wrappers/ruby_llm_query.rb +176 -0
- data/lib/crystil/wrappers/ruby_llm_record.rb +105 -0
- data/lib/crystil/wrappers/ruby_llm_response.rb +148 -0
- data/lib/crystil/wrappers/stopped_call.rb +88 -0
- data/lib/crystil.rb +2 -1
- data/sig/crystil/callables.rbs +6 -0
- data/sig/crystil/client.rbs +2 -0
- data/sig/crystil/collector.rbs +33 -1
- data/sig/crystil/sentinel.rbs +0 -1
- data/sig/crystil/wrappers/anthropic.rbs +12 -0
- data/sig/crystil/wrappers/base.rbs +9 -4
- data/sig/crystil/wrappers/blocked_call.rbs +15 -0
- data/sig/crystil/wrappers/constants.rbs +1 -0
- data/sig/crystil/wrappers/deep_copy.rbs +12 -0
- data/sig/crystil/wrappers/event_stream.rbs +24 -0
- data/sig/crystil/wrappers/geminiai.rbs +11 -0
- data/sig/crystil/wrappers/openai.rbs +12 -0
- data/sig/crystil/wrappers/ruby_llm.rbs +11 -4
- data/sig/crystil/wrappers/ruby_llm_query.rbs +35 -0
- data/sig/crystil/wrappers/ruby_llm_record.rbs +21 -0
- data/sig/crystil/wrappers/ruby_llm_response.rbs +39 -0
- data/sig/crystil/wrappers/stopped_call.rbs +26 -0
- 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
|
-
|
|
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
|
|
91
|
-
#
|
|
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
|
-
|
|
94
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
#
|
|
141
|
-
|
|
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
|