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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +110 -72
- data/README.md +6 -9
- 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 +37 -36
- data/lib/crystil/wrappers/base.rb +25 -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 +21 -26
- data/lib/crystil/wrappers/geminiai.rb +57 -36
- data/lib/crystil/wrappers/google.rb +18 -18
- data/lib/crystil/wrappers/groq.rb +89 -101
- 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/base.rbs +7 -5
- 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 +2 -2
- data/sig/crystil/wrappers/geminiai.rbs +2 -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 +16 -2
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative "ruby_llm_query"
|
|
4
|
+
require_relative "stopped_call"
|
|
5
|
+
|
|
6
|
+
module Crystil
|
|
7
|
+
module Wrappers
|
|
8
|
+
# The response one RubyLLM round records. An unstreamed reply carries the
|
|
9
|
+
# provider's own body. A streamed one keeps none (its `raw.body` is ""), so the
|
|
10
|
+
# reply is recorded as RubyLLM reports it, and the backend reads it in the
|
|
11
|
+
# provider's terms: RubyLLM's token counts are not the provider's.
|
|
12
|
+
module RubyLLMResponse
|
|
13
|
+
module_function
|
|
14
|
+
|
|
15
|
+
# `streamed_model_id` is the first model the round's chunks named (`Chunks#model_id`).
|
|
16
|
+
def build(reply, streamed_model_id = nil)
|
|
17
|
+
body = reply.raw&.body
|
|
18
|
+
return body if body.is_a?(Hash)
|
|
19
|
+
|
|
20
|
+
reply_data(reply, streamed_model_id)
|
|
21
|
+
rescue StandardError => e
|
|
22
|
+
warn "Crystil: Failed to record a RubyLLM reply: #{e.message}"
|
|
23
|
+
body
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# RubyLLM's `Message#to_h` fields, under its names, inside one `ruby_llm_reply` key.
|
|
27
|
+
# A `with_schema` reply's parsed Hash is the JSON the provider sent. The backend quarantines
|
|
28
|
+
# a field it does not know, so a new field here needs a backend release that reads it first.
|
|
29
|
+
def reply_data(reply, streamed_model_id = nil)
|
|
30
|
+
{
|
|
31
|
+
"ruby_llm_reply" => {
|
|
32
|
+
"model_id" => model_id_of(reply, streamed_model_id),
|
|
33
|
+
"content" => RubyLLMQuery.text_of(reply.content),
|
|
34
|
+
"tool_calls" => RubyLLMQuery.tool_calls_data(reply.tool_calls),
|
|
35
|
+
"thinking" => reply.thinking&.text,
|
|
36
|
+
"input_tokens" => reply.input_tokens,
|
|
37
|
+
"output_tokens" => reply.output_tokens,
|
|
38
|
+
"cached_tokens" => reply.cached_tokens,
|
|
39
|
+
"cache_creation_tokens" => reply.cache_creation_tokens,
|
|
40
|
+
"thinking_tokens" => reply.thinking_tokens
|
|
41
|
+
}.compact
|
|
42
|
+
}
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# The gem keeps the first chunk's model, and Azure's first chunk, from its content
|
|
46
|
+
# filter, names "". Then the first model a chunk did name is recorded instead.
|
|
47
|
+
def model_id_of(reply, streamed_model_id)
|
|
48
|
+
return reply.model_id unless reply.model_id.to_s.empty?
|
|
49
|
+
|
|
50
|
+
streamed_model_id || reply.model_id
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
# The app's streaming block, wrapped to keep the chunks of one round, so a
|
|
54
|
+
# stream the app stops is recorded with the reply as far as it got. The
|
|
55
|
+
# gem's own `StreamAccumulator` joins them, as it does for a whole reply.
|
|
56
|
+
class Chunks
|
|
57
|
+
attr_reader :caller_block, :app_block
|
|
58
|
+
# The first model a chunk named.
|
|
59
|
+
attr_reader :model_id
|
|
60
|
+
|
|
61
|
+
def initialize(block)
|
|
62
|
+
@app_block = block
|
|
63
|
+
@caller_block = StoppedCall::CallerBlock.new(block)
|
|
64
|
+
@accumulator = defined?(::RubyLLM::StreamAccumulator) ? ::RubyLLM::StreamAccumulator.new : nil
|
|
65
|
+
@received = false
|
|
66
|
+
@model_id = nil
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
def to_proc
|
|
70
|
+
chunks = self
|
|
71
|
+
@to_proc ||= proc { |chunk| chunks.add(chunk) }
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
# True for the proc this object made, which the gem passes on to the next tool round.
|
|
75
|
+
def made?(block)
|
|
76
|
+
!@to_proc.nil? && block.equal?(@to_proc)
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
def add(chunk)
|
|
80
|
+
keep(chunk)
|
|
81
|
+
@caller_block.call(chunk)
|
|
82
|
+
end
|
|
83
|
+
|
|
84
|
+
# The reply so far, as `RubyLLMResponse.reply_data` records a whole one, or nil before any chunk.
|
|
85
|
+
def reply_so_far
|
|
86
|
+
return nil unless @received && @accumulator
|
|
87
|
+
|
|
88
|
+
RubyLLMResponse.reply_data(@accumulator.to_message(nil), @model_id)
|
|
89
|
+
rescue JSON::ParserError
|
|
90
|
+
unfinished_reply
|
|
91
|
+
rescue StandardError
|
|
92
|
+
nil
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
private
|
|
96
|
+
|
|
97
|
+
# Stopped partway through a tool call's arguments, which `to_message` cannot parse:
|
|
98
|
+
# the text so far, and each tool call with its arguments as the String received.
|
|
99
|
+
def unfinished_reply
|
|
100
|
+
text = @accumulator.content
|
|
101
|
+
{
|
|
102
|
+
"ruby_llm_reply" => {
|
|
103
|
+
"model_id" => @model_id || @accumulator.model_id,
|
|
104
|
+
"content" => text.empty? ? nil : text,
|
|
105
|
+
"tool_calls" => RubyLLMQuery.tool_calls_data(@accumulator.tool_calls)
|
|
106
|
+
}.compact
|
|
107
|
+
}
|
|
108
|
+
rescue StandardError
|
|
109
|
+
nil
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
# A chunk that cannot be kept is skipped: the record must never be why the call fails.
|
|
113
|
+
def keep(chunk)
|
|
114
|
+
remember_model(chunk)
|
|
115
|
+
@accumulator&.add(own_copy(chunk))
|
|
116
|
+
@received = true
|
|
117
|
+
rescue StandardError
|
|
118
|
+
nil
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
# The gem's accumulator keeps a tool call's first arguments String and appends the later
|
|
122
|
+
# fragments to it. Ours gets its own copy, or both would append each fragment to one String.
|
|
123
|
+
def own_copy(chunk)
|
|
124
|
+
calls = chunk.respond_to?(:tool_calls) ? chunk.tool_calls : nil
|
|
125
|
+
return chunk if calls.nil? || calls.empty?
|
|
126
|
+
|
|
127
|
+
::RubyLLM::Chunk.new(
|
|
128
|
+
role: chunk.role, model_id: chunk.model_id, content: chunk.content, thinking: chunk.thinking,
|
|
129
|
+
tokens: chunk.tokens, tool_calls: calls.transform_values { |call| own_tool_call(call) }
|
|
130
|
+
)
|
|
131
|
+
end
|
|
132
|
+
|
|
133
|
+
def own_tool_call(call)
|
|
134
|
+
::RubyLLM::ToolCall.new(
|
|
135
|
+
id: call.id, name: call.name, arguments: call.arguments.dup, thought_signature: call.thought_signature
|
|
136
|
+
)
|
|
137
|
+
end
|
|
138
|
+
|
|
139
|
+
def remember_model(chunk)
|
|
140
|
+
return if @model_id || !chunk.respond_to?(:model_id)
|
|
141
|
+
|
|
142
|
+
model_id = chunk.model_id
|
|
143
|
+
@model_id = model_id unless model_id.to_s.empty?
|
|
144
|
+
end
|
|
145
|
+
end
|
|
146
|
+
end
|
|
147
|
+
end
|
|
148
|
+
end
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Crystil
|
|
4
|
+
module Wrappers
|
|
5
|
+
# How a wrapper records a call that did not finish: `stopped` when the app
|
|
6
|
+
# ended it, `failed` when the gem, the provider or the network did.
|
|
7
|
+
#
|
|
8
|
+
# The app ends a call from inside its own stream callback or block, by
|
|
9
|
+
# raising, throwing or breaking there (a Stop button, a closed browser tab),
|
|
10
|
+
# or with a signal (Ctrl-C, a job worker shutting down). A stopped call has
|
|
11
|
+
# no `exc`: an error from the app's own code may hold its users' data.
|
|
12
|
+
#
|
|
13
|
+
# Mixed into `Base`, like `BlockedCall`.
|
|
14
|
+
module StoppedCall
|
|
15
|
+
STOPPED_MESSAGE = "Stream stopped by the caller before it finished."
|
|
16
|
+
|
|
17
|
+
# The app's stream callback or block. Calling it through this tells the
|
|
18
|
+
# wrapper whether a call ended inside it: `inside` stays true when the
|
|
19
|
+
# app's code raises, throws or breaks, since the line after it never runs.
|
|
20
|
+
class CallerBlock
|
|
21
|
+
attr_reader :inside
|
|
22
|
+
|
|
23
|
+
def initialize(block)
|
|
24
|
+
@block = block
|
|
25
|
+
@inside = false
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
def call(*args)
|
|
29
|
+
@inside = true
|
|
30
|
+
result = @block.call(*args)
|
|
31
|
+
@inside = false
|
|
32
|
+
result
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# True when the app ended the call. `error` is nil for a `break` or `throw`,
|
|
37
|
+
# which raise nothing. A block Sentinel raised for a call the app made from
|
|
38
|
+
# its callback stays a failure, since Crystil raised it, not the app.
|
|
39
|
+
def crystil_stopped_by_app?(error, caller_block)
|
|
40
|
+
return true if error.is_a?(SignalException)
|
|
41
|
+
return false if error.is_a?(CrystilRequestInterceptedError)
|
|
42
|
+
|
|
43
|
+
caller_block&.inside == true
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# Records a call that did not finish. `received` is what arrived before the
|
|
47
|
+
# app stopped it, in the path's usual shape; `failed_response` is what a
|
|
48
|
+
# failure records, the usual `{ error:, class: }` when nil. With no `error`,
|
|
49
|
+
# a call that ended outside the app's code was cut short: `Thread#kill`,
|
|
50
|
+
# or `Timeout.timeout` on Ruby 3.2, which throws rather than raises.
|
|
51
|
+
# Returns true, so the wrapper can mark the call recorded.
|
|
52
|
+
# `stopped` overrides the check, for a stop that leaves no error or block to read it from.
|
|
53
|
+
def crystil_submit_unfinished_analytics(error, caller_block, method:, kwargs:, start_time:, title:, version:,
|
|
54
|
+
provider: nil, received: nil, failed_response: nil, stopped: nil)
|
|
55
|
+
stopped = crystil_stopped_by_app?(error, caller_block) if stopped.nil?
|
|
56
|
+
if stopped
|
|
57
|
+
crystil_submit_analytics(
|
|
58
|
+
method: method, args: [], kwargs: kwargs,
|
|
59
|
+
response: crystil_received_or_nil(received) || { error: STOPPED_MESSAGE },
|
|
60
|
+
start_time: start_time, end_time: Time.now,
|
|
61
|
+
provider: provider, title: title, version: version, status: "stopped"
|
|
62
|
+
)
|
|
63
|
+
else
|
|
64
|
+
crystil_submit_error_analytics(
|
|
65
|
+
method: method, args: [], kwargs: kwargs,
|
|
66
|
+
error: error || Crystil::StreamError.new(EventStream::STREAM_CUT_SHORT_MESSAGE),
|
|
67
|
+
start_time: start_time, end_time: Time.now,
|
|
68
|
+
provider: provider, title: title, version: version, response: failed_response
|
|
69
|
+
)
|
|
70
|
+
end
|
|
71
|
+
true
|
|
72
|
+
rescue StandardError => e
|
|
73
|
+
# This runs while the app's own error, `break` or `throw` is leaving the
|
|
74
|
+
# call, so anything raised here would take its place.
|
|
75
|
+
warn "Crystil: Failed to record an unfinished call: #{e.message}"
|
|
76
|
+
true
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
private
|
|
80
|
+
|
|
81
|
+
def crystil_received_or_nil(received)
|
|
82
|
+
return nil if received.nil? || (received.respond_to?(:empty?) && received.empty?)
|
|
83
|
+
|
|
84
|
+
received
|
|
85
|
+
end
|
|
86
|
+
end
|
|
87
|
+
end
|
|
88
|
+
end
|
data/lib/crystil.rb
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
require_relative "crystil/version"
|
|
4
4
|
require_relative "crystil/errors"
|
|
5
5
|
require_relative "crystil/config"
|
|
6
|
+
require_relative "crystil/callables"
|
|
6
7
|
require_relative "crystil/sentinel"
|
|
7
8
|
require_relative "crystil/attribution"
|
|
8
9
|
require_relative "crystil/collector"
|
|
@@ -36,7 +37,7 @@ require_relative "crystil/client"
|
|
|
36
37
|
# # Use OpenAI normally - analytics tracked automatically
|
|
37
38
|
# response = openai.chat(
|
|
38
39
|
# parameters: {
|
|
39
|
-
# model: "gpt-
|
|
40
|
+
# model: "gpt-6.1-sol",
|
|
40
41
|
# messages: [{ role: "user", content: "Hello!" }]
|
|
41
42
|
# }
|
|
42
43
|
# )
|
data/sig/crystil/client.rbs
CHANGED
|
@@ -24,6 +24,8 @@ module Crystil
|
|
|
24
24
|
def attribution: (parent_id: String, ?parent_name: String?, ?subsidiary_id: String?, ?subsidiary_name: String?) -> self
|
|
25
25
|
def new_transaction: -> self
|
|
26
26
|
def workflows: -> Crystil::API::Workflows
|
|
27
|
+
# Waits for queued payloads, up to `timeout` seconds; true when none is left. The client keeps working.
|
|
28
|
+
def flush: (?Numeric timeout) -> bool
|
|
27
29
|
def shutdown: -> void
|
|
28
30
|
end
|
|
29
31
|
end
|
data/sig/crystil/collector.rbs
CHANGED
|
@@ -4,16 +4,48 @@ module Crystil
|
|
|
4
4
|
class Collector
|
|
5
5
|
DEFAULT_MAX_RETRIES: Integer
|
|
6
6
|
RETRY_DELAY: Integer
|
|
7
|
+
EXIT_WAIT_SECONDS: Integer
|
|
8
|
+
# ObjectSpace::WeakMap — its signature needs the `objspace` library, which the Steepfile does not load.
|
|
9
|
+
self.@collectors: untyped
|
|
10
|
+
self.@lock: Thread::Mutex
|
|
11
|
+
self.@exit_wait_added: bool
|
|
12
|
+
self.@exit_wait_used: Float
|
|
7
13
|
@config: Crystil::Config
|
|
8
14
|
# Concurrent::ThreadPoolExecutor — no upstream signatures available.
|
|
9
15
|
@executor: untyped
|
|
16
|
+
# Concurrent::AtomicFixnum
|
|
17
|
+
@last_number: untyped
|
|
18
|
+
# Concurrent::Map
|
|
19
|
+
@unsent: untyped
|
|
20
|
+
# The process that made the first send; nil until then.
|
|
21
|
+
@pid: Integer?
|
|
22
|
+
@start_lock: Thread::Mutex
|
|
23
|
+
|
|
24
|
+
# Adds the collector to those the exit wait covers.
|
|
25
|
+
def self.track: (Crystil::Collector collector) -> void
|
|
26
|
+
# Adds an exit hook unless one is still to run; each wait clears the flag.
|
|
27
|
+
def self.add_exit_wait: -> void
|
|
28
|
+
# Waits for every collector within what is left of the budget all exit waits share.
|
|
29
|
+
def self.wait_at_exit: -> bool
|
|
30
|
+
# True when every collector finished sending within `seconds`.
|
|
31
|
+
def self.flush_all: (Numeric seconds) -> bool
|
|
32
|
+
def self.now: -> Float
|
|
10
33
|
|
|
11
34
|
def initialize: (Crystil::Config config) -> void
|
|
12
|
-
def submit_async: (Hash[Symbol, untyped] payload) ->
|
|
35
|
+
def submit_async: (Hash[Symbol, untyped] payload) -> bool
|
|
13
36
|
def submit: (Hash[Symbol, untyped] payload) -> untyped
|
|
37
|
+
# True when every payload queued before the call was sent; false at the timeout. The collector keeps working.
|
|
38
|
+
def flush: (?Numeric timeout) -> bool
|
|
39
|
+
# True when nothing is left to send, a payload queued during the wait included; false at the timeout.
|
|
40
|
+
def wait_until_idle: (Numeric timeout) -> bool
|
|
41
|
+
def idle?: -> bool
|
|
14
42
|
def shutdown: -> void
|
|
15
43
|
|
|
16
44
|
private
|
|
45
|
+
def idle_up_to?: (Integer last) -> bool
|
|
46
|
+
def wait_until: (Numeric timeout) { () -> bool } -> bool
|
|
47
|
+
# The first send in each process: a new map, and the collector joins the exit wait.
|
|
48
|
+
def start_in_this_process: -> void
|
|
17
49
|
def submit_with_retry: (Hash[Symbol, untyped] payload, ?Integer attempt) -> untyped
|
|
18
50
|
def post_to_collector: (Hash[Symbol, untyped] payload) -> untyped
|
|
19
51
|
end
|
data/sig/crystil/sentinel.rbs
CHANGED
|
@@ -12,6 +12,5 @@ module Crystil
|
|
|
12
12
|
private
|
|
13
13
|
def make_relevance_intercept_request: (title: String?, request: Hash[Symbol, untyped], ?provider: String?, ?version: String?) -> [bool, String?]
|
|
14
14
|
def normalize_request: (Hash[Symbol, untyped] request) -> untyped
|
|
15
|
-
def remove_procs: (untyped obj) -> untyped
|
|
16
15
|
end
|
|
17
16
|
end
|
|
@@ -4,21 +4,23 @@ module Crystil
|
|
|
4
4
|
module Wrappers
|
|
5
5
|
module Base
|
|
6
6
|
def crystil_wrap_method: (Symbol method_name, String _provider_name) -> void
|
|
7
|
-
def crystil_submit_analytics: (method: Symbol, args: Array[untyped], kwargs: Hash[Symbol, untyped], response: untyped, start_time: Time, end_time: Time, ?provider: String?, ?title: String?, ?version: String?, ?status: String, ?exception: String?) -> void
|
|
7
|
+
def crystil_submit_analytics: (method: Symbol, args: Array[untyped], kwargs: Hash[Symbol, untyped], response: untyped, start_time: Time, end_time: Time, ?provider: String?, ?title: String?, ?version: String?, ?status: String, ?exception: String?, ?reason: String?) -> void
|
|
8
8
|
def crystil_submit_error_analytics: (method: Symbol, args: Array[untyped], kwargs: Hash[Symbol, untyped], error: Exception, start_time: Time, end_time: Time, ?provider: String?, ?title: String?, ?version: String?, ?response: untyped) -> void
|
|
9
9
|
def crystil_merge_streaming_chunk: (Hash[String | Symbol, untyped] accumulated, Hash[String | Symbol, untyped] chunk) -> Hash[String | Symbol, untyped]
|
|
10
10
|
def crystil_normalize_openai_chunk: (untyped chunk) -> untyped
|
|
11
|
-
#
|
|
12
|
-
#
|
|
11
|
+
# The mixins' methods (`crystil_raise_if_irrelevant!`, `crystil_record_event_stream`, ...)
|
|
12
|
+
# are declared in blocked_call.rbs and event_stream.rbs, not here.
|
|
13
|
+
include BlockedCall
|
|
14
|
+
include DeepCopy
|
|
13
15
|
include EventStream
|
|
16
|
+
include StoppedCall
|
|
14
17
|
|
|
15
18
|
private
|
|
16
19
|
def extract_query: (Symbol _method, Array[untyped] _args, Hash[Symbol, untyped] kwargs) -> Hash[Symbol, untyped]
|
|
17
20
|
def extract_response: (untyped response) -> untyped
|
|
18
21
|
def extract_instance_variables: (untyped obj) -> Hash[Symbol, untyped]
|
|
19
22
|
def serialize_value: (untyped value) -> untyped
|
|
20
|
-
def
|
|
21
|
-
def build_payload: (query: Hash[Symbol, untyped], response: untyped, start_time: Time, end_time: Time, config: Crystil::Config, status: String, ?provider: String?, ?title: String?, ?version: String?, ?exception: String?) -> Hash[Symbol, untyped]
|
|
23
|
+
def build_payload: (query: Hash[Symbol, untyped], response: untyped, start_time: Time, end_time: Time, config: Crystil::Config, status: String, ?provider: String?, ?title: String?, ?version: String?, ?exception: String?, ?reason: String?) -> Hash[Symbol, untyped]
|
|
22
24
|
end
|
|
23
25
|
end
|
|
24
26
|
end
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
module Crystil
|
|
2
|
+
module Wrappers
|
|
3
|
+
module BlockedCall
|
|
4
|
+
# Raises CrystilRequestInterceptedError, after sending the blocked payload, when Sentinel blocks the call.
|
|
5
|
+
def crystil_raise_if_irrelevant!: (request: untyped, start_time: Time, title: String, ?provider: String?, ?version: String?, ?query: untyped) -> void
|
|
6
|
+
|
|
7
|
+
# True for a block raised by the call's own Sentinel check, which is already recorded.
|
|
8
|
+
def crystil_block_already_recorded?: (StandardError error, bool? passed_sentinel) -> bool
|
|
9
|
+
|
|
10
|
+
private
|
|
11
|
+
|
|
12
|
+
def crystil_submit_blocked_analytics: (query: untyped, reason: String, start_time: Time, provider: String?, title: String, version: String?) -> void
|
|
13
|
+
end
|
|
14
|
+
end
|
|
15
|
+
end
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
module Crystil
|
|
2
|
+
module Wrappers
|
|
3
|
+
module DeepCopy
|
|
4
|
+
private
|
|
5
|
+
|
|
6
|
+
# Shares a frozen String; `copies` maps each object already copied to its copy.
|
|
7
|
+
def deep_copy: (untyped obj, ?Hash[untyped, untyped] copies) -> untyped
|
|
8
|
+
def crystil_copy_container: (Hash[untyped, untyped] | Array[untyped] obj, Hash[untyped, untyped] copies) -> untyped
|
|
9
|
+
def crystil_marshal_copy: (untyped obj) -> untyped
|
|
10
|
+
end
|
|
11
|
+
end
|
|
12
|
+
end
|
|
@@ -6,7 +6,6 @@ module Crystil
|
|
|
6
6
|
module Wrappers
|
|
7
7
|
module EventStream
|
|
8
8
|
STREAM_CUT_SHORT_MESSAGE: String
|
|
9
|
-
STREAM_CLOSED_UNREAD_MESSAGE: String
|
|
10
9
|
|
|
11
10
|
# Returns the stream it was given, with only `each` replaced — or
|
|
12
11
|
# untouched when it cannot be patched.
|
|
@@ -15,7 +14,8 @@ module Crystil
|
|
|
15
14
|
def crystil_route_enumerators: (untyped stream) -> void
|
|
16
15
|
# Leaves `close` alone when the object has none.
|
|
17
16
|
def crystil_report_on_close: (untyped closer, Array[Fiber] reading_fibers, ^() -> bool claim_report) { () -> void } -> void
|
|
18
|
-
|
|
17
|
+
# A read that did not finish is recorded as stopped or failed; `stopped` says so outright for a `close`.
|
|
18
|
+
def crystil_report_event_stream: (events: Array[untyped], finished: bool, error: Exception?, caller_block: StoppedCall::CallerBlock?, method: Symbol, kwargs: untyped, start_time: Time, ?stopped: bool?, ?title: String?, ?version: String?) -> void
|
|
19
19
|
def self.crystil_event_to_data: (untyped event) -> untyped
|
|
20
20
|
def self.crystil_event_to_hash: (untyped event) -> untyped
|
|
21
21
|
def self.crystil_deep_copy: (untyped data) -> untyped
|
|
@@ -18,6 +18,8 @@ module Crystil
|
|
|
18
18
|
# Returns `parameters` unchanged when the model is unknown or already
|
|
19
19
|
# present, so the return type follows the input rather than being a Hash.
|
|
20
20
|
def self.parameters_with_model: (untyped parameters, String? model) -> untyped
|
|
21
|
+
# Nil when the app gave no block.
|
|
22
|
+
def self.watched_block: (StoppedCall::CallerBlock? caller_block, Array[untyped] received) -> Proc?
|
|
21
23
|
|
|
22
24
|
private
|
|
23
25
|
def validate_client!: (untyped client) -> void
|
|
@@ -9,6 +9,18 @@ module Crystil
|
|
|
9
9
|
|
|
10
10
|
def initialize: (Crystil::Config config, Crystil::Collector collector, ?Crystil::Sentinel? sentinel) -> void
|
|
11
11
|
def register: (untyped client) -> untyped
|
|
12
|
+
# How many of (chunk, event) to pass a stream callback, as ruby-openai's OpenAI::Stream decides.
|
|
13
|
+
def self.callback_arity: (untyped callback) -> Integer
|
|
14
|
+
TERMINAL_EVENT_TYPES: Array[String]
|
|
15
|
+
NO_TERMINAL_EVENT_MESSAGE: String
|
|
16
|
+
|
|
17
|
+
# The latest terminal event's `response`, `{ "error" => ... }` when only an `error` event came, or nil.
|
|
18
|
+
def self.finished_response: (Array[Hash[String, untyped]] events) -> Hash[String, untyped]?
|
|
19
|
+
def self.error_details: (Hash[String, untyped] error_event) -> Hash[String, untyped]
|
|
20
|
+
# The status to record ("succeeded" or "failed") and the error message, if any.
|
|
21
|
+
def self.outcome: (untyped response) -> [String, String?]
|
|
22
|
+
# The latest event's `response`, or nil when none carried one.
|
|
23
|
+
def self.response_so_far: (Array[Hash[String, untyped]]? events) -> Hash[String, untyped]?
|
|
12
24
|
|
|
13
25
|
private
|
|
14
26
|
def wrap_responses_method: (untyped client) -> void
|
|
@@ -3,6 +3,8 @@
|
|
|
3
3
|
module Crystil
|
|
4
4
|
module Wrappers
|
|
5
5
|
class RubyLLM
|
|
6
|
+
include RubyLLMRecord
|
|
7
|
+
|
|
6
8
|
@config: Crystil::Config
|
|
7
9
|
@collector: Crystil::Collector
|
|
8
10
|
@sentinel: Crystil::Sentinel?
|
|
@@ -12,10 +14,15 @@ module Crystil
|
|
|
12
14
|
|
|
13
15
|
private
|
|
14
16
|
def validate_client!: (untyped client) -> void
|
|
15
|
-
def
|
|
16
|
-
def
|
|
17
|
-
|
|
18
|
-
def
|
|
17
|
+
def agent?: (untyped client) -> bool
|
|
18
|
+
def wrap_complete_method: (untyped chat) -> void
|
|
19
|
+
# Records one level's round; false when that round got no reply.
|
|
20
|
+
def record_round: (untyped chat, Integer history_size, Hash[Symbol, untyped] round, RubyLLMResponse::Chunks? chunks) -> bool
|
|
21
|
+
def record_unfinished: (untyped chat, Exception? error, RubyLLMResponse::Chunks? chunks, Integer history_size, Hash[Symbol, untyped]? round, untyped query) -> void
|
|
22
|
+
def remove_blocked_message: (untyped chat) -> void
|
|
23
|
+
def sentinel_on?: -> bool
|
|
24
|
+
def user_message?: (untyped message) -> bool
|
|
25
|
+
def client_title: (String? provider) -> String
|
|
19
26
|
end
|
|
20
27
|
end
|
|
21
28
|
end
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
module Crystil
|
|
2
|
+
module Wrappers
|
|
3
|
+
module RubyLLMQuery
|
|
4
|
+
# Nil, with a warning, when the query cannot be built.
|
|
5
|
+
def self.for_chat: (untyped chat, ?Array[Hash[Symbol, untyped]] extra_messages) -> Hash[Symbol, untyped]?
|
|
6
|
+
# The model, and no messages (`contents` for Gemini's shape).
|
|
7
|
+
def self.empty_query: (String? provider, String model_id) -> Hash[Symbol, untyped]
|
|
8
|
+
# `messages` holds `{ role:, content:, tool_calls:, tool_call_id: }` entries, each as RubyLLM keeps it.
|
|
9
|
+
def self.build: (String? provider, String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools, ?Hash[Symbol, untyped]? params) -> Hash[Symbol, untyped]
|
|
10
|
+
# The query with the chat's `with_params` values under `params`, when it has any.
|
|
11
|
+
def self.with_params: (Hash[Symbol, untyped] query, Hash[Symbol, untyped]? params) -> Hash[Symbol, untyped]
|
|
12
|
+
def self.messages_query: (String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
|
|
13
|
+
def self.google_query: (String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
|
|
14
|
+
# The query, with `stream: true` on a streamed Anthropic or OpenAI call.
|
|
15
|
+
def self.mark_streamed: (Hash[Symbol, untyped] query, bool streamed, String? provider) -> Hash[Symbol, untyped]
|
|
16
|
+
def self.with_tools: (Hash[Symbol, untyped] query, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
|
|
17
|
+
# A Raw value as it is; anything else as its text.
|
|
18
|
+
def self.message_content: (untyped content) -> untyped
|
|
19
|
+
def self.google_parts: (untyped content) -> untyped
|
|
20
|
+
def self.text_of: (untyped content) -> String
|
|
21
|
+
# True for a `RubyLLM::Content::Raw`, a provider-native value the gem sends as it is.
|
|
22
|
+
def self.raw?: (untyped content) -> bool
|
|
23
|
+
# The entry with an `attachments` list when the content has attachments.
|
|
24
|
+
def self.with_attachments: (Hash[Symbol, untyped] entry, untyped content) -> Hash[Symbol, untyped]
|
|
25
|
+
# The entry with the message's tool calls and the call a tool result answers, when it has them.
|
|
26
|
+
def self.with_tool_calls: (Hash[Symbol, untyped] entry, Hash[Symbol, untyped] message) -> Hash[Symbol, untyped]
|
|
27
|
+
# Tool calls as a list of plain data, in RubyLLM's order; nil when there are none.
|
|
28
|
+
def self.tool_calls_data: (Hash[untyped, untyped]? calls) -> Array[Hash[String, untyped]]?
|
|
29
|
+
def self.attachments_data: (Array[untyped] attachments) -> Array[Hash[Symbol, untyped]]
|
|
30
|
+
def self.attachment_data: (untyped attachment) -> Hash[Symbol, untyped]
|
|
31
|
+
# Encoded once, then kept on the attachment, frozen.
|
|
32
|
+
def self.encoded_once: (untyped attachment) -> String
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
end
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
module Crystil
|
|
2
|
+
module Wrappers
|
|
3
|
+
# Mixed into `Wrappers::RubyLLM`, whose `register`, `sentinel_on?`, `client_title` and `user_message?` it calls.
|
|
4
|
+
module RubyLLMRecord
|
|
5
|
+
private
|
|
6
|
+
|
|
7
|
+
# Patches a Rails `acts_as_chat` record's `to_llm`, `ask` and `say`.
|
|
8
|
+
def wrap_record: (untyped record) -> void
|
|
9
|
+
# Registers the chat, and remembers the newest user row it was built from.
|
|
10
|
+
def register_record_chat: (untyped record, untyped chat) -> void
|
|
11
|
+
# The record's rows: `messages_association`, or `messages` on the legacy acts_as API.
|
|
12
|
+
def record_rows: (untyped record) -> untyped
|
|
13
|
+
# Raises CrystilRequestInterceptedError, after sending the blocked payload, when Sentinel blocks the turn.
|
|
14
|
+
def check_record_turn: (untyped chat, untyped message, untyped with, streamed: bool) -> void
|
|
15
|
+
# The chat built so far plus the rows saved since, or nil when only a rebuild gives the same chat.
|
|
16
|
+
def add_new_rows: (untyped record, Hash[Symbol, untyped] built) -> untyped
|
|
17
|
+
# The new turn's content, as the gem's `acts_as_chat` builds it before saving.
|
|
18
|
+
def record_turn_content: (untyped message, untyped with) -> untyped
|
|
19
|
+
end
|
|
20
|
+
end
|
|
21
|
+
end
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
module Crystil
|
|
2
|
+
module Wrappers
|
|
3
|
+
# The response a RubyLLM round records: the provider's body, or for a streamed
|
|
4
|
+
# reply, which keeps none, the reply as RubyLLM reports it.
|
|
5
|
+
module RubyLLMResponse
|
|
6
|
+
def self.build: (untyped reply, ?String? streamed_model_id) -> untyped
|
|
7
|
+
def self.reply_data: (untyped reply, ?String? streamed_model_id) -> Hash[String, Hash[String, untyped]]
|
|
8
|
+
# The reply's model, or the first one its chunks named when the reply's is blank.
|
|
9
|
+
def self.model_id_of: (untyped reply, String? streamed_model_id) -> String?
|
|
10
|
+
|
|
11
|
+
# The app's streaming block, wrapped to keep the chunks it is given.
|
|
12
|
+
class Chunks
|
|
13
|
+
attr_reader caller_block: StoppedCall::CallerBlock
|
|
14
|
+
# The app's own block, which a tool round's level wraps again.
|
|
15
|
+
attr_reader app_block: Proc
|
|
16
|
+
# The first model a chunk named.
|
|
17
|
+
attr_reader model_id: String?
|
|
18
|
+
|
|
19
|
+
def initialize: (untyped block) -> void
|
|
20
|
+
def to_proc: () -> Proc
|
|
21
|
+
# True for the proc this object made.
|
|
22
|
+
def made?: (untyped block) -> bool
|
|
23
|
+
def add: (untyped chunk) -> untyped
|
|
24
|
+
# Nil before any chunk arrived.
|
|
25
|
+
def reply_so_far: () -> Hash[String, Hash[String, untyped]]?
|
|
26
|
+
|
|
27
|
+
private
|
|
28
|
+
|
|
29
|
+
# The text so far and the tool calls, arguments unparsed; nil if it cannot be read.
|
|
30
|
+
def unfinished_reply: () -> Hash[String, Hash[String, untyped]]?
|
|
31
|
+
def keep: (untyped chunk) -> void
|
|
32
|
+
def remember_model: (untyped chunk) -> void
|
|
33
|
+
# The chunk, with tool calls of its own for Crystil's accumulator.
|
|
34
|
+
def own_copy: (untyped chunk) -> untyped
|
|
35
|
+
def own_tool_call: (untyped call) -> untyped
|
|
36
|
+
end
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
end
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
module Crystil
|
|
2
|
+
module Wrappers
|
|
3
|
+
# Records a call that did not finish: `stopped` when the app ended it, `failed` otherwise.
|
|
4
|
+
module StoppedCall
|
|
5
|
+
STOPPED_MESSAGE: String
|
|
6
|
+
|
|
7
|
+
# The app's stream callback or block; `inside` stays true when a call ends inside it.
|
|
8
|
+
class CallerBlock
|
|
9
|
+
attr_reader inside: bool
|
|
10
|
+
|
|
11
|
+
def initialize: (untyped block) -> void
|
|
12
|
+
def call: (*untyped args) -> untyped
|
|
13
|
+
end
|
|
14
|
+
|
|
15
|
+
# `error` is nil for a `break` or `throw`, which raise nothing.
|
|
16
|
+
def crystil_stopped_by_app?: (Exception? error, CallerBlock? caller_block) -> bool
|
|
17
|
+
|
|
18
|
+
# Always true, so the wrapper can mark the call recorded.
|
|
19
|
+
def crystil_submit_unfinished_analytics: (Exception? error, CallerBlock? caller_block, method: Symbol, kwargs: untyped, start_time: Time, title: String?, version: String?, ?provider: String?, ?received: untyped, ?failed_response: untyped, ?stopped: bool?) -> true
|
|
20
|
+
|
|
21
|
+
private
|
|
22
|
+
|
|
23
|
+
def crystil_received_or_nil: (untyped received) -> untyped
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
end
|