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.
Files changed (43) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +115 -42
  3. data/LICENSE +1 -1
  4. data/README.md +11 -3
  5. data/lib/crystil/callables.rb +24 -0
  6. data/lib/crystil/client.rb +7 -0
  7. data/lib/crystil/collector.rb +127 -4
  8. data/lib/crystil/sentinel.rb +2 -19
  9. data/lib/crystil/version.rb +1 -1
  10. data/lib/crystil/wrappers/anthropic.rb +151 -14
  11. data/lib/crystil/wrappers/base.rb +29 -28
  12. data/lib/crystil/wrappers/blocked_call.rb +52 -0
  13. data/lib/crystil/wrappers/constants.rb +3 -0
  14. data/lib/crystil/wrappers/deep_copy.rb +52 -0
  15. data/lib/crystil/wrappers/event_stream.rb +200 -0
  16. data/lib/crystil/wrappers/geminiai.rb +98 -41
  17. data/lib/crystil/wrappers/google.rb +18 -18
  18. data/lib/crystil/wrappers/groq.rb +96 -108
  19. data/lib/crystil/wrappers/openai.rb +118 -101
  20. data/lib/crystil/wrappers/ruby_llm.rb +150 -101
  21. data/lib/crystil/wrappers/ruby_llm_query.rb +176 -0
  22. data/lib/crystil/wrappers/ruby_llm_record.rb +105 -0
  23. data/lib/crystil/wrappers/ruby_llm_response.rb +148 -0
  24. data/lib/crystil/wrappers/stopped_call.rb +88 -0
  25. data/lib/crystil.rb +2 -1
  26. data/sig/crystil/callables.rbs +6 -0
  27. data/sig/crystil/client.rbs +2 -0
  28. data/sig/crystil/collector.rbs +33 -1
  29. data/sig/crystil/sentinel.rbs +0 -1
  30. data/sig/crystil/wrappers/anthropic.rbs +12 -0
  31. data/sig/crystil/wrappers/base.rbs +9 -4
  32. data/sig/crystil/wrappers/blocked_call.rbs +15 -0
  33. data/sig/crystil/wrappers/constants.rbs +1 -0
  34. data/sig/crystil/wrappers/deep_copy.rbs +12 -0
  35. data/sig/crystil/wrappers/event_stream.rbs +24 -0
  36. data/sig/crystil/wrappers/geminiai.rbs +11 -0
  37. data/sig/crystil/wrappers/openai.rbs +12 -0
  38. data/sig/crystil/wrappers/ruby_llm.rbs +11 -4
  39. data/sig/crystil/wrappers/ruby_llm_query.rbs +35 -0
  40. data/sig/crystil/wrappers/ruby_llm_record.rbs +21 -0
  41. data/sig/crystil/wrappers/ruby_llm_response.rbs +39 -0
  42. data/sig/crystil/wrappers/stopped_call.rbs +26 -0
  43. 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-4",
40
+ # model: "gpt-6.1-sol",
40
41
  # messages: [{ role: "user", content: "Hello!" }]
41
42
  # }
42
43
  # )
@@ -0,0 +1,6 @@
1
+ module Crystil
2
+ module Callables
3
+ # A copy with every callable, at any depth inside Hashes and Arrays, replaced by `true`.
4
+ def self.replace_with_true: (untyped obj) -> untyped
5
+ end
6
+ end
@@ -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
@@ -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) -> void
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
@@ -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: StandardError, start_time: Time, end_time: Time, ?provider: String?, ?title: String?, ?version: String?, ?response: untyped) -> 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
+ 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 deep_copy: (untyped obj) -> untyped
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