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
|
@@ -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
|
|
@@ -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
|
|
@@ -7,12 +7,24 @@ module Crystil
|
|
|
7
7
|
@collector: Crystil::Collector
|
|
8
8
|
@sentinel: Crystil::Sentinel?
|
|
9
9
|
|
|
10
|
+
REQUEST_OPTIONS_KEYS: Array[Symbol | String]
|
|
11
|
+
|
|
10
12
|
def initialize: (Crystil::Config config, Crystil::Collector collector, ?Crystil::Sentinel? sentinel) -> void
|
|
11
13
|
def register: (untyped client) -> untyped
|
|
12
14
|
|
|
15
|
+
# A copy without `request_options`; a non-Hash is handed back unchanged.
|
|
16
|
+
def self.recorded_params: (untyped params) -> untyped
|
|
17
|
+
# `untyped` in, `untyped` out: the caller's params are whatever the gem
|
|
18
|
+
# accepts, and a non-Hash is handed back unchanged.
|
|
19
|
+
def self.streamed_query: (untyped params) -> untyped
|
|
20
|
+
# nil when there is no readable event stream, so nothing is recorded.
|
|
21
|
+
def self.raw_event_stream: (untyped stream, Symbol method_name) -> untyped?
|
|
22
|
+
|
|
13
23
|
private
|
|
14
24
|
def validate_client!: (untyped client) -> void
|
|
15
25
|
def wrap_messages_method: (untyped client) -> void
|
|
26
|
+
def wrap_create_method: (untyped messages_resource) -> void
|
|
27
|
+
def wrap_streaming_method: (untyped messages_resource, Symbol method_name) -> void
|
|
16
28
|
end
|
|
17
29
|
end
|
|
18
30
|
end
|
|
@@ -4,18 +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
|
|
8
|
-
def crystil_submit_error_analytics: (method: Symbol, args: Array[untyped], kwargs: Hash[Symbol, untyped], error:
|
|
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
|
+
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
|
+
# 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
|
|
15
|
+
include EventStream
|
|
16
|
+
include StoppedCall
|
|
11
17
|
|
|
12
18
|
private
|
|
13
19
|
def extract_query: (Symbol _method, Array[untyped] _args, Hash[Symbol, untyped] kwargs) -> Hash[Symbol, untyped]
|
|
14
20
|
def extract_response: (untyped response) -> untyped
|
|
15
21
|
def extract_instance_variables: (untyped obj) -> Hash[Symbol, untyped]
|
|
16
22
|
def serialize_value: (untyped value) -> untyped
|
|
17
|
-
def
|
|
18
|
-
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]
|
|
19
24
|
end
|
|
20
25
|
end
|
|
21
26
|
end
|