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,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
@@ -0,0 +1,24 @@
1
+ # Signatures for the list-shaped streaming recorder. `untyped` throughout on
2
+ # the stream and event surface: the objects come from whichever provider gem
3
+ # the caller registered, and the module deliberately knows nothing about them
4
+ # beyond `each`.
5
+ module Crystil
6
+ module Wrappers
7
+ module EventStream
8
+ STREAM_CUT_SHORT_MESSAGE: String
9
+
10
+ # Returns the stream it was given, with only `each` replaced — or
11
+ # untouched when it cannot be patched.
12
+ def crystil_record_event_stream: (untyped stream, method: Symbol, kwargs: untyped, start_time: Time, ?title: String?, ?version: String?, ?closer: untyped) -> untyped
13
+ # Overrides `to_enum` / `enum_for` so external iteration goes through the recorded `each`.
14
+ def crystil_route_enumerators: (untyped stream) -> void
15
+ # Leaves `close` alone when the object has none.
16
+ def crystil_report_on_close: (untyped closer, Array[Fiber] reading_fibers, ^() -> bool claim_report) { () -> void } -> 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
+ def self.crystil_event_to_data: (untyped event) -> untyped
20
+ def self.crystil_event_to_hash: (untyped event) -> untyped
21
+ def self.crystil_deep_copy: (untyped data) -> untyped
22
+ end
23
+ end
24
+ end
@@ -3,6 +3,8 @@
3
3
  module Crystil
4
4
  module Wrappers
5
5
  class GeminiAI
6
+ MODEL_ADDRESS_PATTERN: Regexp
7
+
6
8
  @config: Crystil::Config
7
9
  @collector: Crystil::Collector
8
10
  @sentinel: Crystil::Sentinel?
@@ -10,6 +12,15 @@ module Crystil
10
12
  def initialize: (Crystil::Config config, Crystil::Collector collector, ?Crystil::Sentinel? sentinel) -> void
11
13
  def register: (untyped client) -> untyped
12
14
 
15
+ # Returns nil when the client's @model_address is absent or unreadable.
16
+ def self.extract_model: (untyped client) -> String?
17
+
18
+ # Returns `parameters` unchanged when the model is unknown or already
19
+ # present, so the return type follows the input rather than being a Hash.
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?
23
+
13
24
  private
14
25
  def validate_client!: (untyped client) -> void
15
26
  def wrap_generate_content_method: (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
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: crystil
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.5.0
4
+ version: 0.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Crystil
@@ -39,6 +39,7 @@ files:
39
39
  - lib/crystil/api/workflow.rb
40
40
  - lib/crystil/api/workflows.rb
41
41
  - lib/crystil/attribution.rb
42
+ - lib/crystil/callables.rb
42
43
  - lib/crystil/client.rb
43
44
  - lib/crystil/collector.rb
44
45
  - lib/crystil/config.rb
@@ -47,18 +48,26 @@ files:
47
48
  - lib/crystil/version.rb
48
49
  - lib/crystil/wrappers/anthropic.rb
49
50
  - lib/crystil/wrappers/base.rb
51
+ - lib/crystil/wrappers/blocked_call.rb
50
52
  - lib/crystil/wrappers/constants.rb
53
+ - lib/crystil/wrappers/deep_copy.rb
54
+ - lib/crystil/wrappers/event_stream.rb
51
55
  - lib/crystil/wrappers/geminiai.rb
52
56
  - lib/crystil/wrappers/google.rb
53
57
  - lib/crystil/wrappers/groq.rb
54
58
  - lib/crystil/wrappers/openai.rb
55
59
  - lib/crystil/wrappers/ruby_llm.rb
60
+ - lib/crystil/wrappers/ruby_llm_query.rb
61
+ - lib/crystil/wrappers/ruby_llm_record.rb
62
+ - lib/crystil/wrappers/ruby_llm_response.rb
63
+ - lib/crystil/wrappers/stopped_call.rb
56
64
  - sig/crystil/api/base.rbs
57
65
  - sig/crystil/api/invocation.rbs
58
66
  - sig/crystil/api/sentinel.rbs
59
67
  - sig/crystil/api/workflow.rbs
60
68
  - sig/crystil/api/workflows.rbs
61
69
  - sig/crystil/attribution.rbs
70
+ - sig/crystil/callables.rbs
62
71
  - sig/crystil/client.rbs
63
72
  - sig/crystil/collector.rbs
64
73
  - sig/crystil/config.rbs
@@ -67,12 +76,19 @@ files:
67
76
  - sig/crystil/version.rbs
68
77
  - sig/crystil/wrappers/anthropic.rbs
69
78
  - sig/crystil/wrappers/base.rbs
79
+ - sig/crystil/wrappers/blocked_call.rbs
70
80
  - sig/crystil/wrappers/constants.rbs
81
+ - sig/crystil/wrappers/deep_copy.rbs
82
+ - sig/crystil/wrappers/event_stream.rbs
71
83
  - sig/crystil/wrappers/geminiai.rbs
72
84
  - sig/crystil/wrappers/google.rbs
73
85
  - sig/crystil/wrappers/groq.rbs
74
86
  - sig/crystil/wrappers/openai.rbs
75
87
  - sig/crystil/wrappers/ruby_llm.rbs
88
+ - sig/crystil/wrappers/ruby_llm_query.rbs
89
+ - sig/crystil/wrappers/ruby_llm_record.rbs
90
+ - sig/crystil/wrappers/ruby_llm_response.rbs
91
+ - sig/crystil/wrappers/stopped_call.rbs
76
92
  homepage: https://crystil.com
77
93
  licenses:
78
94
  - MIT
@@ -94,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
94
110
  - !ruby/object:Gem::Version
95
111
  version: '0'
96
112
  requirements: []
97
- rubygems_version: 4.0.18
113
+ rubygems_version: 4.0.24
98
114
  specification_version: 4
99
115
  summary: Cost visibility for AI agents
100
116
  test_files: []