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.
Files changed (41) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +110 -72
  3. data/README.md +6 -9
  4. data/lib/crystil/callables.rb +24 -0
  5. data/lib/crystil/client.rb +7 -0
  6. data/lib/crystil/collector.rb +127 -4
  7. data/lib/crystil/sentinel.rb +2 -19
  8. data/lib/crystil/version.rb +1 -1
  9. data/lib/crystil/wrappers/anthropic.rb +37 -36
  10. data/lib/crystil/wrappers/base.rb +25 -28
  11. data/lib/crystil/wrappers/blocked_call.rb +52 -0
  12. data/lib/crystil/wrappers/constants.rb +3 -0
  13. data/lib/crystil/wrappers/deep_copy.rb +52 -0
  14. data/lib/crystil/wrappers/event_stream.rb +21 -26
  15. data/lib/crystil/wrappers/geminiai.rb +57 -36
  16. data/lib/crystil/wrappers/google.rb +18 -18
  17. data/lib/crystil/wrappers/groq.rb +89 -101
  18. data/lib/crystil/wrappers/openai.rb +118 -101
  19. data/lib/crystil/wrappers/ruby_llm.rb +150 -101
  20. data/lib/crystil/wrappers/ruby_llm_query.rb +176 -0
  21. data/lib/crystil/wrappers/ruby_llm_record.rb +105 -0
  22. data/lib/crystil/wrappers/ruby_llm_response.rb +148 -0
  23. data/lib/crystil/wrappers/stopped_call.rb +88 -0
  24. data/lib/crystil.rb +2 -1
  25. data/sig/crystil/callables.rbs +6 -0
  26. data/sig/crystil/client.rbs +2 -0
  27. data/sig/crystil/collector.rbs +33 -1
  28. data/sig/crystil/sentinel.rbs +0 -1
  29. data/sig/crystil/wrappers/base.rbs +7 -5
  30. data/sig/crystil/wrappers/blocked_call.rbs +15 -0
  31. data/sig/crystil/wrappers/constants.rbs +1 -0
  32. data/sig/crystil/wrappers/deep_copy.rbs +12 -0
  33. data/sig/crystil/wrappers/event_stream.rbs +2 -2
  34. data/sig/crystil/wrappers/geminiai.rbs +2 -0
  35. data/sig/crystil/wrappers/openai.rbs +12 -0
  36. data/sig/crystil/wrappers/ruby_llm.rbs +11 -4
  37. data/sig/crystil/wrappers/ruby_llm_query.rbs +35 -0
  38. data/sig/crystil/wrappers/ruby_llm_record.rbs +21 -0
  39. data/sig/crystil/wrappers/ruby_llm_response.rbs +39 -0
  40. data/sig/crystil/wrappers/stopped_call.rbs +26 -0
  41. 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
- # Ask method handles both streaming and non-streaming cases unlike some others.
31
- wrap_ask_method(client)
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?(:ask)
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 ask method)"
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
- def wrap_ask_method(client)
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
- client.singleton_class.class_eval do
74
+ chat.singleton_class.class_eval do
51
75
  include Base
52
76
 
53
- alias_method :original_ask, :ask
77
+ alias_method :original_complete, :complete
54
78
 
55
- define_method(:ask) do |message, with: nil, &block|
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
- query = {} # Fallback for error analytics if an exception occurs before build_query completes
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
- sentinel = instance_variable_get(:@crystil_sentinel)
63
- provider = model.provider
64
- # Telemetry invariant: `conversation.client.title` is never nil.
65
- # `model.provider` should always return a non-empty string for
66
- # well-formed RubyLLM models, but fall back to the meta-wrapper
67
- # name (matches JS's pattern of "fallback to the SDK family
68
- # name") if it ever isn't.
69
- title = case provider
70
- when "gemini" then GOOGLE_CLIENT_TITLE
71
- when nil, "" then RUBY_LLM_PROVIDER
72
- else provider
73
- end
74
-
75
- # Capture existing messages (e.g. system instruction) before the call
76
- # adds the new user message to history.
77
- existing_msgs = messages.map { |m| { role: m.role.to_s, content: m.content.to_s } }
78
- all_msgs = existing_msgs + [{ role: "user", content: message.to_s }]
79
-
80
- # Build a query in the provider's native format so the backend extractor can parse it.
81
- query = wrapper.send(:build_query, provider, model.id, all_msgs, tools)
82
-
83
- # Pass the actual provider title (e.g. "anthropic", "openai", "google") so the
84
- # sentinel backend can route to the correct classifier for this request format.
85
- sentinel&.raise_if_irrelevant!(title: title, request: query, version: version)
86
-
87
- response = original_ask(message, with: with, &block)
88
-
89
- crystil_submit_analytics(
90
- method: :ask,
91
- args: [],
92
- kwargs: query,
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 CrystilRequestInterceptedError => e
103
- raise e
104
- rescue StandardError => e
105
- crystil_submit_error_analytics(
106
- method: :ask,
107
- args: [],
108
- kwargs: query,
109
- error: e,
110
- start_time: start_time,
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
- # Dispatches to the appropriate provider-native query builder.
122
- def build_query(provider, model_id, messages, tools)
123
- if provider == "gemini"
124
- build_google_query(model_id, messages, tools)
125
- else
126
- # Anthropic and OpenAI have the same query format
127
- build_messages_query(model_id, messages, tools)
128
- end
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
- # Builds an OpenAI-compatible query (used for Anthropic and OpenAI providers).
132
- def build_messages_query(model_id, messages, tools)
133
- query = { model: model_id, messages: messages }
134
- unless tools.empty?
135
- query[:tools] = tools.values.map do |t|
136
- { name: t.name, description: t.description, parameters: t.params_schema }
137
- end
138
- end
139
- query
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
- # Builds a Google-native query with contents/systemInstruction structure.
143
- def build_google_query(model_id, messages, tools)
144
- system_msgs = messages.select { |m| m[:role] == "system" }
145
- content_msgs = messages.reject { |m| m[:role] == "system" }
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
- query = {
148
- model: model_id,
149
- contents: content_msgs.map do |m|
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
- if system_msgs.any?
156
- system_text = system_msgs.map { |m| m[:content] }.join("\n")
157
- query[:systemInstruction] = { parts: [{ text: system_text }] }
158
- end
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
- unless tools.empty?
161
- query[:tools] = tools.values.map do |t|
162
- { name: t.name, description: t.description, parameters: t.params_schema }
163
- end
164
- end
199
+ def sentinel_on?
200
+ !@sentinel.nil? && @config.raise_if_irrelevant
201
+ end
165
202
 
166
- query
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