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
@@ -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
@@ -4,21 +4,23 @@ module Crystil
4
4
  module Wrappers
5
5
  module Base
6
6
  def crystil_wrap_method: (Symbol method_name, String _provider_name) -> void
7
- def crystil_submit_analytics: (method: Symbol, args: Array[untyped], kwargs: Hash[Symbol, untyped], response: untyped, start_time: Time, end_time: Time, ?provider: String?, ?title: String?, ?version: String?, ?status: String, ?exception: String?) -> void
7
+ def crystil_submit_analytics: (method: Symbol, args: Array[untyped], kwargs: Hash[Symbol, untyped], response: untyped, start_time: Time, end_time: Time, ?provider: String?, ?title: String?, ?version: String?, ?status: String, ?exception: String?, ?reason: String?) -> void
8
8
  def crystil_submit_error_analytics: (method: Symbol, args: Array[untyped], kwargs: Hash[Symbol, untyped], error: Exception, start_time: Time, end_time: Time, ?provider: String?, ?title: String?, ?version: String?, ?response: untyped) -> void
9
9
  def crystil_merge_streaming_chunk: (Hash[String | Symbol, untyped] accumulated, Hash[String | Symbol, untyped] chunk) -> Hash[String | Symbol, untyped]
10
10
  def crystil_normalize_openai_chunk: (untyped chunk) -> untyped
11
- # `crystil_record_event_stream` / `crystil_report_event_stream` arrive via
12
- # `include EventStream`; they are declared in event_stream.rbs, not here.
11
+ # The mixins' methods (`crystil_raise_if_irrelevant!`, `crystil_record_event_stream`, ...)
12
+ # are declared in blocked_call.rbs and event_stream.rbs, not here.
13
+ include BlockedCall
14
+ include DeepCopy
13
15
  include EventStream
16
+ include StoppedCall
14
17
 
15
18
  private
16
19
  def extract_query: (Symbol _method, Array[untyped] _args, Hash[Symbol, untyped] kwargs) -> Hash[Symbol, untyped]
17
20
  def extract_response: (untyped response) -> untyped
18
21
  def extract_instance_variables: (untyped obj) -> Hash[Symbol, untyped]
19
22
  def serialize_value: (untyped value) -> untyped
20
- def deep_copy: (untyped obj) -> untyped
21
- def build_payload: (query: Hash[Symbol, untyped], response: untyped, start_time: Time, end_time: Time, config: Crystil::Config, status: String, ?provider: String?, ?title: String?, ?version: String?, ?exception: String?) -> Hash[Symbol, untyped]
23
+ def build_payload: (query: Hash[Symbol, untyped], response: untyped, start_time: Time, end_time: Time, config: Crystil::Config, status: String, ?provider: String?, ?title: String?, ?version: String?, ?exception: String?, ?reason: String?) -> Hash[Symbol, untyped]
22
24
  end
23
25
  end
24
26
  end
@@ -0,0 +1,15 @@
1
+ module Crystil
2
+ module Wrappers
3
+ module BlockedCall
4
+ # Raises CrystilRequestInterceptedError, after sending the blocked payload, when Sentinel blocks the call.
5
+ def crystil_raise_if_irrelevant!: (request: untyped, start_time: Time, title: String, ?provider: String?, ?version: String?, ?query: untyped) -> void
6
+
7
+ # True for a block raised by the call's own Sentinel check, which is already recorded.
8
+ def crystil_block_already_recorded?: (StandardError error, bool? passed_sentinel) -> bool
9
+
10
+ private
11
+
12
+ def crystil_submit_blocked_analytics: (query: untyped, reason: String, start_time: Time, provider: String?, title: String, version: String?) -> void
13
+ end
14
+ end
15
+ end
@@ -6,5 +6,6 @@ module Crystil
6
6
  GOOGLE_CLIENT_TITLE: String
7
7
  RUBY_LLM_PROVIDER: String
8
8
  GROQ_PROVIDER: String
9
+ RUBY_LLM_GEMINI_PROVIDERS: Array[String]
9
10
  end
10
11
  end
@@ -0,0 +1,12 @@
1
+ module Crystil
2
+ module Wrappers
3
+ module DeepCopy
4
+ private
5
+
6
+ # Shares a frozen String; `copies` maps each object already copied to its copy.
7
+ def deep_copy: (untyped obj, ?Hash[untyped, untyped] copies) -> untyped
8
+ def crystil_copy_container: (Hash[untyped, untyped] | Array[untyped] obj, Hash[untyped, untyped] copies) -> untyped
9
+ def crystil_marshal_copy: (untyped obj) -> untyped
10
+ end
11
+ end
12
+ end
@@ -6,7 +6,6 @@ module Crystil
6
6
  module Wrappers
7
7
  module EventStream
8
8
  STREAM_CUT_SHORT_MESSAGE: String
9
- STREAM_CLOSED_UNREAD_MESSAGE: String
10
9
 
11
10
  # Returns the stream it was given, with only `each` replaced — or
12
11
  # untouched when it cannot be patched.
@@ -15,7 +14,8 @@ module Crystil
15
14
  def crystil_route_enumerators: (untyped stream) -> void
16
15
  # Leaves `close` alone when the object has none.
17
16
  def crystil_report_on_close: (untyped closer, Array[Fiber] reading_fibers, ^() -> bool claim_report) { () -> void } -> void
18
- def crystil_report_event_stream: (events: Array[untyped], error: Exception?, method: Symbol, kwargs: untyped, start_time: Time, ?title: String?, ?version: String?) -> void
17
+ # A read that did not finish is recorded as stopped or failed; `stopped` says so outright for a `close`.
18
+ def crystil_report_event_stream: (events: Array[untyped], finished: bool, error: Exception?, caller_block: StoppedCall::CallerBlock?, method: Symbol, kwargs: untyped, start_time: Time, ?stopped: bool?, ?title: String?, ?version: String?) -> void
19
19
  def self.crystil_event_to_data: (untyped event) -> untyped
20
20
  def self.crystil_event_to_hash: (untyped event) -> untyped
21
21
  def self.crystil_deep_copy: (untyped data) -> untyped
@@ -18,6 +18,8 @@ module Crystil
18
18
  # Returns `parameters` unchanged when the model is unknown or already
19
19
  # present, so the return type follows the input rather than being a Hash.
20
20
  def self.parameters_with_model: (untyped parameters, String? model) -> untyped
21
+ # Nil when the app gave no block.
22
+ def self.watched_block: (StoppedCall::CallerBlock? caller_block, Array[untyped] received) -> Proc?
21
23
 
22
24
  private
23
25
  def validate_client!: (untyped client) -> void
@@ -9,6 +9,18 @@ module Crystil
9
9
 
10
10
  def initialize: (Crystil::Config config, Crystil::Collector collector, ?Crystil::Sentinel? sentinel) -> void
11
11
  def register: (untyped client) -> untyped
12
+ # How many of (chunk, event) to pass a stream callback, as ruby-openai's OpenAI::Stream decides.
13
+ def self.callback_arity: (untyped callback) -> Integer
14
+ TERMINAL_EVENT_TYPES: Array[String]
15
+ NO_TERMINAL_EVENT_MESSAGE: String
16
+
17
+ # The latest terminal event's `response`, `{ "error" => ... }` when only an `error` event came, or nil.
18
+ def self.finished_response: (Array[Hash[String, untyped]] events) -> Hash[String, untyped]?
19
+ def self.error_details: (Hash[String, untyped] error_event) -> Hash[String, untyped]
20
+ # The status to record ("succeeded" or "failed") and the error message, if any.
21
+ def self.outcome: (untyped response) -> [String, String?]
22
+ # The latest event's `response`, or nil when none carried one.
23
+ def self.response_so_far: (Array[Hash[String, untyped]]? events) -> Hash[String, untyped]?
12
24
 
13
25
  private
14
26
  def wrap_responses_method: (untyped client) -> void
@@ -3,6 +3,8 @@
3
3
  module Crystil
4
4
  module Wrappers
5
5
  class RubyLLM
6
+ include RubyLLMRecord
7
+
6
8
  @config: Crystil::Config
7
9
  @collector: Crystil::Collector
8
10
  @sentinel: Crystil::Sentinel?
@@ -12,10 +14,15 @@ module Crystil
12
14
 
13
15
  private
14
16
  def validate_client!: (untyped client) -> void
15
- def wrap_ask_method: (untyped client) -> void
16
- def build_query: (String provider, String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
17
- def build_messages_query: (String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
18
- def build_google_query: (String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
17
+ def agent?: (untyped client) -> bool
18
+ def wrap_complete_method: (untyped chat) -> void
19
+ # Records one level's round; false when that round got no reply.
20
+ def record_round: (untyped chat, Integer history_size, Hash[Symbol, untyped] round, RubyLLMResponse::Chunks? chunks) -> bool
21
+ def record_unfinished: (untyped chat, Exception? error, RubyLLMResponse::Chunks? chunks, Integer history_size, Hash[Symbol, untyped]? round, untyped query) -> void
22
+ def remove_blocked_message: (untyped chat) -> void
23
+ def sentinel_on?: -> bool
24
+ def user_message?: (untyped message) -> bool
25
+ def client_title: (String? provider) -> String
19
26
  end
20
27
  end
21
28
  end
@@ -0,0 +1,35 @@
1
+ module Crystil
2
+ module Wrappers
3
+ module RubyLLMQuery
4
+ # Nil, with a warning, when the query cannot be built.
5
+ def self.for_chat: (untyped chat, ?Array[Hash[Symbol, untyped]] extra_messages) -> Hash[Symbol, untyped]?
6
+ # The model, and no messages (`contents` for Gemini's shape).
7
+ def self.empty_query: (String? provider, String model_id) -> Hash[Symbol, untyped]
8
+ # `messages` holds `{ role:, content:, tool_calls:, tool_call_id: }` entries, each as RubyLLM keeps it.
9
+ def self.build: (String? provider, String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools, ?Hash[Symbol, untyped]? params) -> Hash[Symbol, untyped]
10
+ # The query with the chat's `with_params` values under `params`, when it has any.
11
+ def self.with_params: (Hash[Symbol, untyped] query, Hash[Symbol, untyped]? params) -> Hash[Symbol, untyped]
12
+ def self.messages_query: (String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
13
+ def self.google_query: (String model_id, Array[Hash[Symbol, untyped]] messages, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
14
+ # The query, with `stream: true` on a streamed Anthropic or OpenAI call.
15
+ def self.mark_streamed: (Hash[Symbol, untyped] query, bool streamed, String? provider) -> Hash[Symbol, untyped]
16
+ def self.with_tools: (Hash[Symbol, untyped] query, Hash[Symbol, untyped] tools) -> Hash[Symbol, untyped]
17
+ # A Raw value as it is; anything else as its text.
18
+ def self.message_content: (untyped content) -> untyped
19
+ def self.google_parts: (untyped content) -> untyped
20
+ def self.text_of: (untyped content) -> String
21
+ # True for a `RubyLLM::Content::Raw`, a provider-native value the gem sends as it is.
22
+ def self.raw?: (untyped content) -> bool
23
+ # The entry with an `attachments` list when the content has attachments.
24
+ def self.with_attachments: (Hash[Symbol, untyped] entry, untyped content) -> Hash[Symbol, untyped]
25
+ # The entry with the message's tool calls and the call a tool result answers, when it has them.
26
+ def self.with_tool_calls: (Hash[Symbol, untyped] entry, Hash[Symbol, untyped] message) -> Hash[Symbol, untyped]
27
+ # Tool calls as a list of plain data, in RubyLLM's order; nil when there are none.
28
+ def self.tool_calls_data: (Hash[untyped, untyped]? calls) -> Array[Hash[String, untyped]]?
29
+ def self.attachments_data: (Array[untyped] attachments) -> Array[Hash[Symbol, untyped]]
30
+ def self.attachment_data: (untyped attachment) -> Hash[Symbol, untyped]
31
+ # Encoded once, then kept on the attachment, frozen.
32
+ def self.encoded_once: (untyped attachment) -> String
33
+ end
34
+ end
35
+ end
@@ -0,0 +1,21 @@
1
+ module Crystil
2
+ module Wrappers
3
+ # Mixed into `Wrappers::RubyLLM`, whose `register`, `sentinel_on?`, `client_title` and `user_message?` it calls.
4
+ module RubyLLMRecord
5
+ private
6
+
7
+ # Patches a Rails `acts_as_chat` record's `to_llm`, `ask` and `say`.
8
+ def wrap_record: (untyped record) -> void
9
+ # Registers the chat, and remembers the newest user row it was built from.
10
+ def register_record_chat: (untyped record, untyped chat) -> void
11
+ # The record's rows: `messages_association`, or `messages` on the legacy acts_as API.
12
+ def record_rows: (untyped record) -> untyped
13
+ # Raises CrystilRequestInterceptedError, after sending the blocked payload, when Sentinel blocks the turn.
14
+ def check_record_turn: (untyped chat, untyped message, untyped with, streamed: bool) -> void
15
+ # The chat built so far plus the rows saved since, or nil when only a rebuild gives the same chat.
16
+ def add_new_rows: (untyped record, Hash[Symbol, untyped] built) -> untyped
17
+ # The new turn's content, as the gem's `acts_as_chat` builds it before saving.
18
+ def record_turn_content: (untyped message, untyped with) -> untyped
19
+ end
20
+ end
21
+ end
@@ -0,0 +1,39 @@
1
+ module Crystil
2
+ module Wrappers
3
+ # The response a RubyLLM round records: the provider's body, or for a streamed
4
+ # reply, which keeps none, the reply as RubyLLM reports it.
5
+ module RubyLLMResponse
6
+ def self.build: (untyped reply, ?String? streamed_model_id) -> untyped
7
+ def self.reply_data: (untyped reply, ?String? streamed_model_id) -> Hash[String, Hash[String, untyped]]
8
+ # The reply's model, or the first one its chunks named when the reply's is blank.
9
+ def self.model_id_of: (untyped reply, String? streamed_model_id) -> String?
10
+
11
+ # The app's streaming block, wrapped to keep the chunks it is given.
12
+ class Chunks
13
+ attr_reader caller_block: StoppedCall::CallerBlock
14
+ # The app's own block, which a tool round's level wraps again.
15
+ attr_reader app_block: Proc
16
+ # The first model a chunk named.
17
+ attr_reader model_id: String?
18
+
19
+ def initialize: (untyped block) -> void
20
+ def to_proc: () -> Proc
21
+ # True for the proc this object made.
22
+ def made?: (untyped block) -> bool
23
+ def add: (untyped chunk) -> untyped
24
+ # Nil before any chunk arrived.
25
+ def reply_so_far: () -> Hash[String, Hash[String, untyped]]?
26
+
27
+ private
28
+
29
+ # The text so far and the tool calls, arguments unparsed; nil if it cannot be read.
30
+ def unfinished_reply: () -> Hash[String, Hash[String, untyped]]?
31
+ def keep: (untyped chunk) -> void
32
+ def remember_model: (untyped chunk) -> void
33
+ # The chunk, with tool calls of its own for Crystil's accumulator.
34
+ def own_copy: (untyped chunk) -> untyped
35
+ def own_tool_call: (untyped call) -> untyped
36
+ end
37
+ end
38
+ end
39
+ end
@@ -0,0 +1,26 @@
1
+ module Crystil
2
+ module Wrappers
3
+ # Records a call that did not finish: `stopped` when the app ended it, `failed` otherwise.
4
+ module StoppedCall
5
+ STOPPED_MESSAGE: String
6
+
7
+ # The app's stream callback or block; `inside` stays true when a call ends inside it.
8
+ class CallerBlock
9
+ attr_reader inside: bool
10
+
11
+ def initialize: (untyped block) -> void
12
+ def call: (*untyped args) -> untyped
13
+ end
14
+
15
+ # `error` is nil for a `break` or `throw`, which raise nothing.
16
+ def crystil_stopped_by_app?: (Exception? error, CallerBlock? caller_block) -> bool
17
+
18
+ # Always true, so the wrapper can mark the call recorded.
19
+ def crystil_submit_unfinished_analytics: (Exception? error, CallerBlock? caller_block, method: Symbol, kwargs: untyped, start_time: Time, title: String?, version: String?, ?provider: String?, ?received: untyped, ?failed_response: untyped, ?stopped: bool?) -> true
20
+
21
+ private
22
+
23
+ def crystil_received_or_nil: (untyped received) -> untyped
24
+ end
25
+ end
26
+ end