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
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require_relative "constants"
|
|
4
|
+
require_relative "ruby_llm_query"
|
|
5
|
+
require_relative "ruby_llm_response"
|
|
6
|
+
require_relative "ruby_llm_record"
|
|
4
7
|
|
|
5
8
|
module Crystil
|
|
6
9
|
module Wrappers
|
|
@@ -9,6 +12,8 @@ module Crystil
|
|
|
9
12
|
# Returns raw response and raw formatted query to backend so that the existing
|
|
10
13
|
# extractors can be used.
|
|
11
14
|
class RubyLLM
|
|
15
|
+
include RubyLLMRecord
|
|
16
|
+
|
|
12
17
|
def initialize(config, collector, sentinel = nil)
|
|
13
18
|
@config = config
|
|
14
19
|
@collector = collector
|
|
@@ -18,6 +23,13 @@ module Crystil
|
|
|
18
23
|
def register(client)
|
|
19
24
|
validate_client!(client)
|
|
20
25
|
|
|
26
|
+
# An agent forwards `ask` to its chat, whose `ask` calls the chat's own
|
|
27
|
+
# `complete`, so the chat is what gets wrapped. It may be a Rails record.
|
|
28
|
+
if agent?(client)
|
|
29
|
+
register(client.chat)
|
|
30
|
+
return client
|
|
31
|
+
end
|
|
32
|
+
|
|
21
33
|
# Prevent double registration
|
|
22
34
|
return client if client.instance_variable_defined?(:@crystil_registered)
|
|
23
35
|
|
|
@@ -27,8 +39,11 @@ module Crystil
|
|
|
27
39
|
client.instance_variable_set(:@crystil_sentinel, @sentinel)
|
|
28
40
|
client.instance_variable_set(:@crystil_registered, true)
|
|
29
41
|
|
|
30
|
-
|
|
31
|
-
|
|
42
|
+
if client.respond_to?(:to_llm)
|
|
43
|
+
wrap_record(client)
|
|
44
|
+
else
|
|
45
|
+
wrap_complete_method(client)
|
|
46
|
+
end
|
|
32
47
|
|
|
33
48
|
client
|
|
34
49
|
end
|
|
@@ -36,134 +51,168 @@ module Crystil
|
|
|
36
51
|
private
|
|
37
52
|
|
|
38
53
|
def validate_client!(client)
|
|
39
|
-
return if client.respond_to?(:
|
|
54
|
+
return if client.respond_to?(:complete)
|
|
40
55
|
|
|
41
56
|
raise RegistrationError,
|
|
42
|
-
"Client does not appear to be a valid RubyLLM client (missing
|
|
57
|
+
"Client does not appear to be a valid RubyLLM client (missing complete method)"
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
def agent?(client)
|
|
61
|
+
return false unless defined?(::RubyLLM::Agent)
|
|
62
|
+
|
|
63
|
+
client.is_a?(::RubyLLM::Agent)
|
|
43
64
|
end
|
|
44
65
|
|
|
45
|
-
|
|
66
|
+
# Every call to the provider goes through `complete`: `ask` and its alias
|
|
67
|
+
# `say` add the user's message to `messages`, then call it, and a caller can
|
|
68
|
+
# do the same with `add_message`. Handles streaming and non-streaming alike.
|
|
69
|
+
def wrap_complete_method(chat)
|
|
46
70
|
# Capture the wrapper instance in a local variable so it's accessible as a closure
|
|
47
71
|
# inside the block, where self will no longer refer to it.
|
|
48
72
|
wrapper = self
|
|
49
73
|
|
|
50
|
-
|
|
74
|
+
chat.singleton_class.class_eval do
|
|
51
75
|
include Base
|
|
52
76
|
|
|
53
|
-
alias_method :
|
|
77
|
+
alias_method :original_complete, :complete
|
|
54
78
|
|
|
55
|
-
define_method(:
|
|
79
|
+
define_method(:complete) do |*args, **kwargs, &block|
|
|
80
|
+
# Each level of `complete` makes one provider call: a tool round calls
|
|
81
|
+
# `complete` again from inside this one. So every level records its own
|
|
82
|
+
# round, and only the outermost asks Sentinel.
|
|
83
|
+
outermost = !@crystil_completing
|
|
84
|
+
@crystil_completing = true
|
|
85
|
+
@crystil_round_starts = [] if outermost
|
|
56
86
|
start_time = Time.now
|
|
57
|
-
|
|
87
|
+
level = @crystil_round_starts.size
|
|
88
|
+
@crystil_round_starts << start_time
|
|
89
|
+
history_size = messages.size
|
|
90
|
+
query = {} # Fallback for error analytics if an exception occurs before the query is built
|
|
58
91
|
# Version reported is RubyLLM's, not the underlying provider's — RubyLLM is the
|
|
59
92
|
# meta-wrapper Crystil sees; the native provider gem may not even be loaded.
|
|
60
93
|
version = defined?(::RubyLLM::VERSION) ? ::RubyLLM::VERSION : nil
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
#
|
|
66
|
-
#
|
|
67
|
-
#
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
#
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
response: response.raw&.body,
|
|
94
|
-
start_time: start_time,
|
|
95
|
-
end_time: Time.now,
|
|
96
|
-
title: title,
|
|
97
|
-
provider: RUBY_LLM_PROVIDER,
|
|
98
|
-
version: version
|
|
99
|
-
)
|
|
100
|
-
|
|
94
|
+
title = wrapper.send(:client_title, model.provider)
|
|
95
|
+
# A block streams the reply; the gem passes it on to each tool round.
|
|
96
|
+
round = { start_time: start_time, level: level, title: title, version: version, streamed: !block.nil? }
|
|
97
|
+
|
|
98
|
+
# A query in the provider's native format, so the backend extractor can parse it.
|
|
99
|
+
# It is the history this level's provider call is sent, new user turn included.
|
|
100
|
+
# Nil when it cannot be built: the round then records no messages, and Sentinel is skipped.
|
|
101
|
+
built = RubyLLMQuery.for_chat(self)
|
|
102
|
+
round[:query] = built || RubyLLMQuery.empty_query(model.provider, model.id)
|
|
103
|
+
query = RubyLLMQuery.mark_streamed(round[:query], round[:streamed], model.provider)
|
|
104
|
+
|
|
105
|
+
# A Rails record's `ask` asks Sentinel itself, before it saves the user's message.
|
|
106
|
+
checked_by_record = @crystil_turn_checked
|
|
107
|
+
@crystil_turn_checked = false
|
|
108
|
+
if outermost && !checked_by_record && built
|
|
109
|
+
# The provider title (e.g. "anthropic") routes Sentinel to the matching classifier.
|
|
110
|
+
crystil_raise_if_irrelevant!(
|
|
111
|
+
title: title, request: round[:query], query: query, start_time: start_time,
|
|
112
|
+
provider: RUBY_LLM_PROVIDER, version: version
|
|
113
|
+
)
|
|
114
|
+
end
|
|
115
|
+
passed_sentinel = true
|
|
116
|
+
|
|
117
|
+
# The app's block streams the reply; it is wrapped to keep what arrives, for a stream the app stops.
|
|
118
|
+
# A tool round gets the outer level's wrapper back from the gem, so it wraps the app's own block.
|
|
119
|
+
app_block = @crystil_chunks&.made?(block) ? @crystil_chunks.app_block : block
|
|
120
|
+
chunks = app_block && RubyLLMResponse::Chunks.new(app_block)
|
|
121
|
+
@crystil_chunks = chunks
|
|
122
|
+
response = original_complete(*args, **kwargs, &chunks)
|
|
123
|
+
recorded = true
|
|
124
|
+
# A `Halt` from a tool has no `raw`, so the round is read from the history.
|
|
125
|
+
wrapper.send(:record_round, self, history_size, round, chunks)
|
|
101
126
|
response
|
|
102
|
-
rescue
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
end_time: Time.now,
|
|
112
|
-
title: title,
|
|
113
|
-
provider: RUBY_LLM_PROVIDER,
|
|
114
|
-
version: version
|
|
115
|
-
)
|
|
127
|
+
rescue SignalException, StandardError => e
|
|
128
|
+
if crystil_block_already_recorded?(e, passed_sentinel)
|
|
129
|
+
# Sentinel judges only the newest user message, so one left in history
|
|
130
|
+
# would reach the provider with the next allowed turn.
|
|
131
|
+
wrapper.send(:remove_blocked_message, self)
|
|
132
|
+
raise e
|
|
133
|
+
end
|
|
134
|
+
|
|
135
|
+
error = e
|
|
116
136
|
raise e
|
|
137
|
+
ensure
|
|
138
|
+
# Recorded here, not in the rescue: a `break` or `throw` from the app's block raises nothing.
|
|
139
|
+
if !recorded && passed_sentinel
|
|
140
|
+
wrapper.send(:record_unfinished, self, error, chunks, history_size, round, query)
|
|
141
|
+
end
|
|
142
|
+
if outermost
|
|
143
|
+
@crystil_completing = false
|
|
144
|
+
@crystil_chunks = nil
|
|
145
|
+
end
|
|
117
146
|
end
|
|
118
147
|
end
|
|
119
148
|
end
|
|
120
149
|
|
|
121
|
-
#
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
150
|
+
# Records one level's round from the reply its provider call added to the history:
|
|
151
|
+
# the first assistant message after `history_size`. It ends when the next level began,
|
|
152
|
+
# if one did, or now. False when the round got no reply. A telemetry error never escapes.
|
|
153
|
+
def record_round(chat, history_size, round, chunks)
|
|
154
|
+
reply = chat.messages.drop(history_size).find { |m| m.role.to_s == "assistant" }
|
|
155
|
+
return false unless reply
|
|
156
|
+
|
|
157
|
+
next_start = chat.instance_variable_get(:@crystil_round_starts)[round[:level] + 1]
|
|
158
|
+
query = RubyLLMQuery.mark_streamed(round[:query], round[:streamed], chat.model.provider)
|
|
159
|
+
chat.crystil_submit_analytics(
|
|
160
|
+
method: :complete, args: [], kwargs: query, response: RubyLLMResponse.build(reply, chunks&.model_id),
|
|
161
|
+
start_time: round[:start_time], end_time: next_start || Time.now,
|
|
162
|
+
title: round[:title], provider: RUBY_LLM_PROVIDER, version: round[:version]
|
|
163
|
+
)
|
|
164
|
+
true
|
|
165
|
+
rescue StandardError => e
|
|
166
|
+
warn "Crystil: Failed to record a RubyLLM round: #{e.message}"
|
|
167
|
+
true
|
|
129
168
|
end
|
|
130
169
|
|
|
131
|
-
#
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
170
|
+
# Records a level whose `complete` did not return. One whose provider call got its
|
|
171
|
+
# reply records that round, since what ended it came later, in a tool or a later
|
|
172
|
+
# round, which records itself. Otherwise the call was stopped by the app or failed.
|
|
173
|
+
def record_unfinished(chat, error, chunks, history_size, round, query)
|
|
174
|
+
return if round.nil? || record_round(chat, history_size, round, chunks)
|
|
175
|
+
|
|
176
|
+
chat.crystil_submit_unfinished_analytics(
|
|
177
|
+
error, chunks&.caller_block,
|
|
178
|
+
method: :complete, kwargs: query, received: chunks&.reply_so_far,
|
|
179
|
+
start_time: round[:start_time], provider: RUBY_LLM_PROVIDER, title: round[:title], version: round[:version]
|
|
180
|
+
)
|
|
140
181
|
end
|
|
141
182
|
|
|
142
|
-
#
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
183
|
+
# Takes the user message Sentinel just blocked back out of the chat's history.
|
|
184
|
+
# For a Rails record, that history is the saved rows, so the row goes too.
|
|
185
|
+
# A failure here is only warned about, so it never replaces the block.
|
|
186
|
+
def remove_blocked_message(chat)
|
|
187
|
+
return unless user_message?(chat.messages.last)
|
|
146
188
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
google_role = m[:role] == "assistant" ? "model" : m[:role]
|
|
151
|
-
{ role: google_role, parts: [{ text: m[:content] }] }
|
|
152
|
-
end
|
|
153
|
-
}
|
|
189
|
+
blocked = chat.messages.pop
|
|
190
|
+
saved_turn = chat.instance_variable_get(:@crystil_saved_turn)
|
|
191
|
+
return unless saved_turn && saved_turn[:message].equal?(blocked)
|
|
154
192
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
193
|
+
# Through the association, so the row also leaves the rows the record has loaded.
|
|
194
|
+
saved_turn[:rows].destroy(saved_turn[:row])
|
|
195
|
+
rescue StandardError => e
|
|
196
|
+
warn "Crystil: Failed to remove a blocked RubyLLM message: #{e.message}"
|
|
197
|
+
end
|
|
159
198
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
end
|
|
164
|
-
end
|
|
199
|
+
def sentinel_on?
|
|
200
|
+
!@sentinel.nil? && @config.raise_if_irrelevant
|
|
201
|
+
end
|
|
165
202
|
|
|
166
|
-
|
|
203
|
+
def user_message?(message)
|
|
204
|
+
!message.nil? && message.role.to_s == "user"
|
|
205
|
+
end
|
|
206
|
+
|
|
207
|
+
# Telemetry invariant: `conversation.client.title` is never nil. `model.provider`
|
|
208
|
+
# should always be a non-empty string for well-formed RubyLLM models, but fall back
|
|
209
|
+
# to the meta-wrapper name (JS's "fallback to the SDK family name") if it ever isn't.
|
|
210
|
+
def client_title(provider)
|
|
211
|
+
case provider
|
|
212
|
+
when "gemini" then GOOGLE_CLIENT_TITLE
|
|
213
|
+
when nil, "" then RUBY_LLM_PROVIDER
|
|
214
|
+
else provider
|
|
215
|
+
end
|
|
167
216
|
end
|
|
168
217
|
end
|
|
169
218
|
end
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
require_relative "constants"
|
|
5
|
+
|
|
6
|
+
module Crystil
|
|
7
|
+
module Wrappers
|
|
8
|
+
# The query a RubyLLM call is recorded as. RubyLLM hides the request it sends, so
|
|
9
|
+
# the messages are rebuilt from the chat's history in the provider's shape. What
|
|
10
|
+
# a message holds beyond its text is recorded as RubyLLM keeps it: a Raw value as
|
|
11
|
+
# it is, and attachments in a list of their own, which the backend renders.
|
|
12
|
+
module RubyLLMQuery
|
|
13
|
+
module_function
|
|
14
|
+
|
|
15
|
+
# The query for a chat's history, plus `extra_messages`. Nil, with a warning, when it
|
|
16
|
+
# cannot be built: the record must never be why the app's call fails.
|
|
17
|
+
def for_chat(chat, extra_messages = [])
|
|
18
|
+
history = chat.messages.map do |m|
|
|
19
|
+
{ role: m.role.to_s, content: m.content, tool_calls: m.tool_calls, tool_call_id: m.tool_call_id }
|
|
20
|
+
end
|
|
21
|
+
build(chat.model.provider, chat.model.id, history + extra_messages, chat.tools, chat.params)
|
|
22
|
+
rescue StandardError => e
|
|
23
|
+
warn "Crystil: Failed to build a RubyLLM query: #{e.message}"
|
|
24
|
+
nil
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
# What a round records when its query cannot be built: the model, and no messages.
|
|
28
|
+
def empty_query(provider, model_id)
|
|
29
|
+
key = RUBY_LLM_GEMINI_PROVIDERS.include?(provider) ? :contents : :messages
|
|
30
|
+
{ model: model_id, key => [] }
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# `messages` holds `{ role:, content:, tool_calls:, tool_call_id: }` entries, each as RubyLLM keeps it.
|
|
34
|
+
def build(provider, model_id, messages, tools, params = {})
|
|
35
|
+
query = if RUBY_LLM_GEMINI_PROVIDERS.include?(provider)
|
|
36
|
+
google_query(model_id, messages, tools)
|
|
37
|
+
else
|
|
38
|
+
# Anthropic and OpenAI share the OpenAI-compatible query format.
|
|
39
|
+
messages_query(model_id, messages, tools)
|
|
40
|
+
end
|
|
41
|
+
with_params(query, params)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
# A chat's `with_params` values, as given. The gem deep-merges them into the request
|
|
45
|
+
# after rendering it, and the backend does the same, so a cache asked for there is seen.
|
|
46
|
+
def with_params(query, params)
|
|
47
|
+
return query if params.nil? || params.empty?
|
|
48
|
+
|
|
49
|
+
query.merge(params: params)
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
def messages_query(model_id, messages, tools)
|
|
53
|
+
messages = messages.map do |m|
|
|
54
|
+
entry = with_attachments({ role: m[:role], content: message_content(m[:content]) }, m[:content])
|
|
55
|
+
with_tool_calls(entry, m)
|
|
56
|
+
end
|
|
57
|
+
with_tools({ model: model_id, messages: messages }, tools)
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
# A Google-native query: `contents` with `role: "model"` for the assistant, and
|
|
61
|
+
# system messages in `systemInstruction`. The gem sends those as user turns, but
|
|
62
|
+
# Sentinel needs a system message, and lets every call through without one.
|
|
63
|
+
def google_query(model_id, messages, tools)
|
|
64
|
+
system_msgs, content_msgs = messages.partition { |m| m[:role] == "system" }
|
|
65
|
+
query = {
|
|
66
|
+
model: model_id,
|
|
67
|
+
contents: content_msgs.map do |m|
|
|
68
|
+
role = m[:role] == "assistant" ? "model" : m[:role]
|
|
69
|
+
entry = with_attachments({ role: role, parts: google_parts(m[:content]) }, m[:content])
|
|
70
|
+
with_tool_calls(entry, m)
|
|
71
|
+
end
|
|
72
|
+
}
|
|
73
|
+
if system_msgs.any?
|
|
74
|
+
system_text = system_msgs.map { |m| text_of(m[:content]) }.join("\n")
|
|
75
|
+
query[:systemInstruction] = { parts: [{ text: system_text }] }
|
|
76
|
+
end
|
|
77
|
+
with_tools(query, tools)
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
# Anthropic and OpenAI mark a streamed request with `stream: true` in its body,
|
|
81
|
+
# and the backend reads a streamed call by it. Gemini, and Vertex AI with its format,
|
|
82
|
+
# stream at another endpoint.
|
|
83
|
+
def mark_streamed(query, streamed, provider)
|
|
84
|
+
return query unless streamed && !RUBY_LLM_GEMINI_PROVIDERS.include?(provider)
|
|
85
|
+
|
|
86
|
+
query.merge(stream: true)
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
def with_tools(query, tools)
|
|
90
|
+
return query if tools.empty?
|
|
91
|
+
|
|
92
|
+
definitions = tools.values.map { |t| { name: t.name, description: t.description, parameters: t.params_schema } }
|
|
93
|
+
query.merge(tools: definitions)
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
# A `RubyLLM::Content::Raw` holds a provider-native value, which the gem sends
|
|
97
|
+
# as it is; anything else is recorded as its text.
|
|
98
|
+
def message_content(content)
|
|
99
|
+
raw?(content) ? content.value : text_of(content)
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
def google_parts(content)
|
|
103
|
+
raw?(content) ? content.value : [{ text: text_of(content) }]
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
# A RubyLLM::Content's `to_s` is only an object id; its text is `text`. A parsed
|
|
107
|
+
# `with_schema` reply, a Hash a Content was built with, or a Raw value where only
|
|
108
|
+
# text fits (Gemini's `systemInstruction`) is recorded as JSON, through `to_json` as
|
|
109
|
+
# the gem's request encodes it: with ActiveSupport loaded, that writes Infinity as null.
|
|
110
|
+
def text_of(content)
|
|
111
|
+
content = content.value if raw?(content)
|
|
112
|
+
content = content.text if content.respond_to?(:text)
|
|
113
|
+
return content.to_json if content.is_a?(Hash) || content.is_a?(Array)
|
|
114
|
+
|
|
115
|
+
content.to_s
|
|
116
|
+
end
|
|
117
|
+
|
|
118
|
+
def raw?(content)
|
|
119
|
+
defined?(::RubyLLM::Content::Raw) ? content.is_a?(::RubyLLM::Content::Raw) : false
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
def with_attachments(entry, content)
|
|
123
|
+
return entry unless content.respond_to?(:attachments) && !content.attachments.empty?
|
|
124
|
+
|
|
125
|
+
entry.merge(attachments: attachments_data(content.attachments))
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
# A message's tool calls, and the call a tool result answers, as RubyLLM keeps them.
|
|
129
|
+
# The backend renders them in the provider's shape (CRY-986).
|
|
130
|
+
def with_tool_calls(entry, message)
|
|
131
|
+
calls = tool_calls_data(message[:tool_calls])
|
|
132
|
+
entry = entry.merge(tool_calls: calls) if calls
|
|
133
|
+
message[:tool_call_id] ? entry.merge(tool_call_id: message[:tool_call_id]) : entry
|
|
134
|
+
end
|
|
135
|
+
|
|
136
|
+
# Tool calls as a list of plain data, in RubyLLM's order, as every provider sends them;
|
|
137
|
+
# a streamed reply records its calls the same way. RubyLLM keeps them in a Hash by call id.
|
|
138
|
+
def tool_calls_data(calls)
|
|
139
|
+
return nil if calls.nil? || calls.empty?
|
|
140
|
+
|
|
141
|
+
calls.values.map { |call| { "id" => call.id, "name" => call.name, "arguments" => call.arguments } }
|
|
142
|
+
end
|
|
143
|
+
|
|
144
|
+
# One that cannot be read is left out: the record must never be why the call
|
|
145
|
+
# fails, and the gem raises its own error if it fails too.
|
|
146
|
+
def attachments_data(attachments)
|
|
147
|
+
attachments.filter_map do |attachment|
|
|
148
|
+
attachment_data(attachment)
|
|
149
|
+
rescue StandardError
|
|
150
|
+
nil
|
|
151
|
+
end
|
|
152
|
+
end
|
|
153
|
+
|
|
154
|
+
# An attachment as RubyLLM holds it: a text file as the text every provider gets,
|
|
155
|
+
# any other file as base64, and a URL as itself, which the SDK never downloads.
|
|
156
|
+
def attachment_data(attachment)
|
|
157
|
+
data = { type: attachment.type.to_s, mime_type: attachment.mime_type, filename: attachment.filename }
|
|
158
|
+
return data.merge(url: attachment.source.to_s) if attachment.url?
|
|
159
|
+
return data.merge(text: attachment.for_llm) if attachment.type == :text
|
|
160
|
+
|
|
161
|
+
data.merge(data: encoded_once(attachment))
|
|
162
|
+
end
|
|
163
|
+
|
|
164
|
+
# An attachment's base64, encoded once and kept on the attachment, frozen, so every
|
|
165
|
+
# round of a tool loop records the same String, which `deep_copy` then shares.
|
|
166
|
+
def encoded_once(attachment)
|
|
167
|
+
cached = attachment.instance_variable_get(:@crystil_encoded)
|
|
168
|
+
return cached if cached
|
|
169
|
+
|
|
170
|
+
encoded = attachment.encoded.dup.freeze
|
|
171
|
+
attachment.instance_variable_set(:@crystil_encoded, encoded) unless attachment.frozen?
|
|
172
|
+
encoded
|
|
173
|
+
end
|
|
174
|
+
end
|
|
175
|
+
end
|
|
176
|
+
end
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative "constants"
|
|
4
|
+
require_relative "ruby_llm_query"
|
|
5
|
+
|
|
6
|
+
module Crystil
|
|
7
|
+
module Wrappers
|
|
8
|
+
# How `Wrappers::RubyLLM` wraps a Rails `acts_as_chat` record, mixed into it so the
|
|
9
|
+
# wrapper class stays within its length limit, as `RubyLLMQuery` does for the query.
|
|
10
|
+
module RubyLLMRecord
|
|
11
|
+
private
|
|
12
|
+
|
|
13
|
+
# A Rails `acts_as_chat` record saves each message as a row, and its `to_llm`
|
|
14
|
+
# rebuilds a plain chat from the rows on every call. So the record's `ask` asks
|
|
15
|
+
# Sentinel before the user's message is saved: a blocked prompt never becomes a
|
|
16
|
+
# row, which a page streaming the chat's messages would otherwise show at once.
|
|
17
|
+
# The record never gets `Base`, whose methods could hide the app's own.
|
|
18
|
+
def wrap_record(record)
|
|
19
|
+
wrapper = self
|
|
20
|
+
original_to_llm = record.method(:to_llm)
|
|
21
|
+
original_ask = record.method(:ask)
|
|
22
|
+
|
|
23
|
+
# The legacy acts_as API's `with_context` calls `to_llm(context:)`.
|
|
24
|
+
record.define_singleton_method(:to_llm) do |*args, **kwargs, &block|
|
|
25
|
+
built = @crystil_built_chat
|
|
26
|
+
@crystil_built_chat = nil
|
|
27
|
+
reused = built && args.empty? && kwargs.empty? && block.nil? && wrapper.send(:add_new_rows, self, built)
|
|
28
|
+
chat = reused || original_to_llm.call(*args, **kwargs, &block)
|
|
29
|
+
wrapper.send(:register_record_chat, self, chat)
|
|
30
|
+
chat
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# Every argument goes through, so a keyword a later gem version adds still works.
|
|
34
|
+
record.define_singleton_method(:ask) do |*args, **kwargs, &block|
|
|
35
|
+
# `to_llm` rebuilds every message and downloads every attachment, so with
|
|
36
|
+
# nothing to check, leave that to the gem's own call.
|
|
37
|
+
return original_ask.call(*args, **kwargs, &block) unless wrapper.send(:sentinel_on?)
|
|
38
|
+
|
|
39
|
+
chat = to_llm
|
|
40
|
+
wrapper.send(:check_record_turn, chat, args.first, kwargs[:with], streamed: !block.nil?)
|
|
41
|
+
chat.instance_variable_set(:@crystil_turn_checked, true)
|
|
42
|
+
# The gem's `complete` calls `to_llm` again, after saving the user's row; it gets this chat.
|
|
43
|
+
@crystil_built_chat = { chat: chat, row_count: wrapper.send(:record_rows, self).to_a.size }
|
|
44
|
+
original_ask.call(*args, **kwargs, &block)
|
|
45
|
+
ensure
|
|
46
|
+
@crystil_built_chat = nil
|
|
47
|
+
chat&.instance_variable_set(:@crystil_turn_checked, false)
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# The gem's `alias say ask` still points at its own `ask`.
|
|
51
|
+
record.define_singleton_method(:say) { |*args, **kwargs, &block| ask(*args, **kwargs, &block) }
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
# Registers the plain chat a record's `to_llm` returns. It also remembers the newest
|
|
55
|
+
# user row the chat was built from, and the message built from it, so a block raised
|
|
56
|
+
# inside the chat destroys that row and no other.
|
|
57
|
+
def register_record_chat(record, chat)
|
|
58
|
+
register(chat)
|
|
59
|
+
rows = record_rows(record)
|
|
60
|
+
newest_row = rows.to_a.reverse.find { |row| user_message?(row) } # loaded by `to_llm`, so no query
|
|
61
|
+
newest_message = chat.messages.reverse.find { |message| user_message?(message) }
|
|
62
|
+
chat.instance_variable_set(:@crystil_saved_turn, { rows: rows, row: newest_row, message: newest_message })
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
# Adds the rows saved since `built[:chat]` was built, as the gem's `to_llm` adds them,
|
|
66
|
+
# instead of rebuilding every message and reading every file again. Nil when only a
|
|
67
|
+
# rebuild gives the same chat: a new system row, which the gem orders first, or a row gone.
|
|
68
|
+
def add_new_rows(record, built)
|
|
69
|
+
rows = record_rows(record).to_a
|
|
70
|
+
new_rows = rows.drop(built[:row_count])
|
|
71
|
+
return nil if rows.size < built[:row_count] || new_rows.any? { |row| row.role.to_s == "system" }
|
|
72
|
+
|
|
73
|
+
new_rows.each { |row| built[:chat].add_message(row.to_llm) }
|
|
74
|
+
built[:chat]
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# The legacy acts_as API names the rows' association `messages`.
|
|
78
|
+
def record_rows(record)
|
|
79
|
+
record.respond_to?(:messages_association) ? record.messages_association : record.messages
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
# Asks Sentinel about a record's new turn before the gem saves it, judging the
|
|
83
|
+
# saved history plus the new message, as the provider would get them.
|
|
84
|
+
def check_record_turn(chat, message, with, streamed:)
|
|
85
|
+
query = RubyLLMQuery.for_chat(chat, [{ role: "user", content: record_turn_content(message, with) }])
|
|
86
|
+
return unless query
|
|
87
|
+
|
|
88
|
+
provider = chat.model.provider
|
|
89
|
+
chat.crystil_raise_if_irrelevant!(
|
|
90
|
+
title: client_title(provider), request: query, start_time: Time.now,
|
|
91
|
+
query: RubyLLMQuery.mark_streamed(query, streamed, provider),
|
|
92
|
+
provider: RUBY_LLM_PROVIDER, version: defined?(::RubyLLM::VERSION) ? ::RubyLLM::VERSION : nil
|
|
93
|
+
)
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
# The new turn's content, built as the gem's `acts_as_chat` builds it before saving.
|
|
97
|
+
# A content object the caller built already carries its own attachments.
|
|
98
|
+
def record_turn_content(message, with)
|
|
99
|
+
return message if with.nil? || message.is_a?(::RubyLLM::Content) || message.is_a?(::RubyLLM::Content::Raw)
|
|
100
|
+
|
|
101
|
+
::RubyLLM::Content.new(message, with)
|
|
102
|
+
end
|
|
103
|
+
end
|
|
104
|
+
end
|
|
105
|
+
end
|