crystil 0.5.0

data/lib/crystil/wrappers/openai.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Crystil
+  module Wrappers
+    # Wrapper for OpenAI Ruby client (ruby-openai gem)
+    class OpenAI
+      def initialize(config, collector, sentinel = nil)
+        @config = config
+        @collector = collector
+        @sentinel = sentinel
+      end
+
+      def register(client)
+        validate_client!(client)
+
+        # Prevent double registration
+        return client if client.instance_variable_defined?(:@crystil_registered)
+
+        # Store references in client instance
+        client.instance_variable_set(:@crystil_config, @config)
+        client.instance_variable_set(:@crystil_collector, @collector)
+        client.instance_variable_set(:@crystil_sentinel, @sentinel)
+        client.instance_variable_set(:@crystil_registered, true)
+
+        # Wrap the chat method
+        wrap_chat_method(client)
+
+        # Wrap responses.create if the client supports the Responses API (ruby-openai >= 8.0)
+        wrap_responses_method(client) if client.respond_to?(:responses)
+
+        client
+      end
+
+      private
+
+      def wrap_responses_method(client)
+        responses_obj = client.responses
+
+        # Copy Crystil references onto the responses sub-object so Base helpers can access them
+        responses_obj.instance_variable_set(:@crystil_config, client.instance_variable_get(:@crystil_config))
+        responses_obj.instance_variable_set(:@crystil_collector, client.instance_variable_get(:@crystil_collector))
+        responses_obj.instance_variable_set(:@crystil_sentinel, client.instance_variable_get(:@crystil_sentinel))
+
+        responses_obj.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_create, :create
+
+          define_method(:create) do |parameters: {}|
+            start_time = Time.now
+            version = defined?(::OpenAI::VERSION) ? ::OpenAI::VERSION : nil
+
+            sentinel = instance_variable_get(:@crystil_sentinel)
+            sentinel&.raise_if_irrelevant!(
+              title: OPENAI_CLIENT_TITLE,
+              request: parameters,
+              version: version
+            )
+
+            # Dup before mutating so we don't replace the caller's :stream key with our
+            # internal wrapping proc — the caller's hash should be unchanged after the call.
+            parameters = parameters.dup
+
+            streaming = parameters[:stream].respond_to?(:call)
+
+            if streaming
+              accumulated_events = []
+              user_callback = parameters[:stream]
+              # Determine how many arguments to forward to the user's callback.
+              # .arity returns negative values for methods with optional/splat params
+              # (e.g. def call(*args) => -1, def call(a, b=nil) => -2), so .abs gives
+              # us the minimum required argument count. For fixed-arity procs/lambdas
+              # this is exact. Note: a variadic callable (def call(*args)) has arity -1,
+              # so .abs yields 1 — the event_type argument will be silently dropped for
+              # that signature. Use def call(event, event_type = nil) to receive both.
+              user_callback_arity =
+                case user_callback
+                when Proc
+                  user_callback.arity.abs
+                else
+                  user_callback.method(:call).arity.abs
+                end
+
+              parameters[:stream] = proc do |chunk, event_type|
+                accumulated_events << chunk if chunk.is_a?(Hash)
+                user_callback.call(*[chunk, event_type].first(user_callback_arity))
+              end
+            end
+
+            response = original_create(parameters: parameters)
+
+            # Default to the returned response; for streaming, replace it with the
+            # full response from the terminal response.completed event.
+            final_response = response
+
+            if streaming
+              error_event = accumulated_events.find { |e| e["type"] == "error" }
+              if error_event
+                final_response = {
+                  "status" => "failed",
+                  "error" => error_event["error"]
+                }
+              end
+
+              # Extract the full response from the terminal response.completed event.
+              # A missing terminal event means the stream was interrupted.
+              completed = accumulated_events.find { |e| e["type"] == "response.completed" }
+              unless completed || error_event
+                raise StreamError,
+                      "Responses API stream ended without response.completed event"
+              end
+
+              final_response = completed["response"] if completed && !error_event
+            end
+
+            # Treat only an explicit failed response status as failed analytics.
+            # Other non-exceptional statuses are still recorded as succeeded.
+            response_status = final_response.is_a?(Hash) ? final_response["status"] : nil
+            analytics_status = response_status == "failed" ? "failed" : "succeeded"
+            analytics_exception =
+              if analytics_status == "failed"
+                final_response.dig("error", "message") ||
+                  "OpenAI response status: #{response_status || "unknown"}"
+              end
+
+            crystil_submit_analytics(
+              method: :create,
+              args: [],
+              kwargs: parameters,
+              response: final_response,
+              start_time: start_time,
+              end_time: Time.now,
+              title: OPENAI_CLIENT_TITLE,
+              version: version,
+              status: analytics_status,
+              exception: analytics_exception
+            )
+
+            response
+          rescue CrystilRequestInterceptedError => e
+            raise e
+          rescue StandardError => e
+            crystil_submit_error_analytics(
+              method: :create,
+              args: [],
+              kwargs: parameters,
+              error: e,
+              start_time: start_time,
+              end_time: Time.now,
+              title: OPENAI_CLIENT_TITLE,
+              version: version
+            )
+            raise e
+          end
+        end
+      end
+
+      def validate_client!(client)
+        # When register an OpenAI client, it currently only checks if there
+        # is the classic "chat" interface.  OpenAI now supports the newer
+        # "responses" interface.  So, if an OpenAI client later only has
+        # the newer "responses" interface, this validate_client will fail.
+        return if client.respond_to?(:chat)
+
+        raise RegistrationError, "Client does not appear to be a valid OpenAI client (missing chat method)"
+      end
+
+      def wrap_chat_method(client)
+        client.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_chat, :chat
+
+          define_method(:chat) do |parameters: {}|
+            start_time = Time.now
+            version = defined?(::OpenAI::VERSION) ? ::OpenAI::VERSION : nil
+
+            sentinel = instance_variable_get(:@crystil_sentinel)
+            sentinel&.raise_if_irrelevant!(
+              title: OPENAI_CLIENT_TITLE,
+              request: parameters,
+              version: version
+            )
+
+            # Detect streaming and wrap callback to accumulate chunks
+            streaming = parameters[:stream].is_a?(Proc)
+            accumulated_response = {} if streaming
+
+            if streaming
+              # Configure streaming to include usage (matches Python SDK behavior).
+              # A caller-set value (true or false) wins — we only force `true`
+              # when the key is absent.
+              parameters[:stream_options] ||= {}
+              parameters[:stream_options][:include_usage] = true unless parameters[:stream_options].key?(:include_usage)
+
+              user_callback = parameters[:stream]
+              parameters[:stream] = proc do |chunk, bytesize|
+                # Normalize chunk to match Python SDK format (add missing delta keys with nil)
+                normalized_chunk = crystil_normalize_openai_chunk(chunk)
+                # Accumulate chunk (merge into accumulated_response)
+                crystil_merge_streaming_chunk(accumulated_response, normalized_chunk)
+                # Call user's original callback with original chunk (don't modify user's data)
+                user_callback.call(chunk, bytesize)
+              end
+            end
+
+            # Call the original method
+            response = original_chat(parameters: parameters)
+
+            # Use accumulated response for streaming, otherwise use returned response
+            final_response = streaming ? accumulated_response : response
+
+            # Submit analytics
+            crystil_submit_analytics(
+              method: :chat,
+              args: [],
+              kwargs: parameters,
+              response: final_response,
+              start_time: start_time,
+              end_time: Time.now,
+              title: OPENAI_CLIENT_TITLE,
+              version: version
+            )
+
+            response
+          rescue CrystilRequestInterceptedError => e
+            # We don't want to send intercepts to collector
+            raise e
+          rescue StandardError => e
+            crystil_submit_error_analytics(
+              method: :chat,
+              args: [],
+              kwargs: parameters,
+              error: e,
+              start_time: start_time,
+              end_time: Time.now,
+              title: OPENAI_CLIENT_TITLE,
+              version: version
+            )
+
+            raise e
+          end
+        end
+      end
+    end
+  end
+end

data/lib/crystil/wrappers/ruby_llm.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Crystil
+  module Wrappers
+    # Wrapper for RubyLLM (ruby_llm gem)
+    # Supports any provider available via RubyLLM (Anthropic, OpenAI, Google, etc.)
+    # Returns raw response and raw formatted query to backend so that the existing
+    # extractors can be used.
+    class RubyLLM
+      def initialize(config, collector, sentinel = nil)
+        @config = config
+        @collector = collector
+        @sentinel = sentinel
+      end
+
+      def register(client)
+        validate_client!(client)
+
+        # Prevent double registration
+        return client if client.instance_variable_defined?(:@crystil_registered)
+
+        # Store references in the client instance
+        client.instance_variable_set(:@crystil_config, @config)
+        client.instance_variable_set(:@crystil_collector, @collector)
+        client.instance_variable_set(:@crystil_sentinel, @sentinel)
+        client.instance_variable_set(:@crystil_registered, true)
+
+        # Ask method handles both streaming and non-streaming cases unlike some others.
+        wrap_ask_method(client)
+
+        client
+      end
+
+      private
+
+      def validate_client!(client)
+        return if client.respond_to?(:ask)
+
+        raise RegistrationError,
+              "Client does not appear to be a valid RubyLLM client (missing ask method)"
+      end
+
+      def wrap_ask_method(client)
+        # Capture the wrapper instance in a local variable so it's accessible as a closure
+        # inside the block, where self will no longer refer to it.
+        wrapper = self
+
+        client.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_ask, :ask
+
+          define_method(:ask) do |message, with: nil, &block|
+            start_time = Time.now
+            query = {} # Fallback for error analytics if an exception occurs before build_query completes
+            # Version reported is RubyLLM's, not the underlying provider's — RubyLLM is the
+            # meta-wrapper Crystil sees; the native provider gem may not even be loaded.
+            version = defined?(::RubyLLM::VERSION) ? ::RubyLLM::VERSION : nil
+
+            sentinel = instance_variable_get(:@crystil_sentinel)
+            provider = model.provider
+            # Telemetry invariant: `conversation.client.title` is never nil.
+            # `model.provider` should always return a non-empty string for
+            # well-formed RubyLLM models, but fall back to the meta-wrapper
+            # name (matches JS's pattern of "fallback to the SDK family
+            # name") if it ever isn't.
+            title = case provider
+                    when "gemini" then GOOGLE_CLIENT_TITLE
+                    when nil, "" then RUBY_LLM_PROVIDER
+                    else provider
+                    end
+
+            # Capture existing messages (e.g. system instruction) before the call
+            # adds the new user message to history.
+            existing_msgs = messages.map { |m| { role: m.role.to_s, content: m.content.to_s } }
+            all_msgs = existing_msgs + [{ role: "user", content: message.to_s }]
+
+            # Build a query in the provider's native format so the backend extractor can parse it.
+            query = wrapper.send(:build_query, provider, model.id, all_msgs, tools)
+
+            # Pass the actual provider title (e.g. "anthropic", "openai", "google") so the
+            # sentinel backend can route to the correct classifier for this request format.
+            sentinel&.raise_if_irrelevant!(title: title, request: query, version: version)
+
+            response = original_ask(message, with: with, &block)
+
+            crystil_submit_analytics(
+              method: :ask,
+              args: [],
+              kwargs: query,
+              response: response.raw&.body,
+              start_time: start_time,
+              end_time: Time.now,
+              title: title,
+              provider: RUBY_LLM_PROVIDER,
+              version: version
+            )
+
+            response
+          rescue CrystilRequestInterceptedError => e
+            raise e
+          rescue StandardError => e
+            crystil_submit_error_analytics(
+              method: :ask,
+              args: [],
+              kwargs: query,
+              error: e,
+              start_time: start_time,
+              end_time: Time.now,
+              title: title,
+              provider: RUBY_LLM_PROVIDER,
+              version: version
+            )
+            raise e
+          end
+        end
+      end
+
+      # Dispatches to the appropriate provider-native query builder.
+      def build_query(provider, model_id, messages, tools)
+        if provider == "gemini"
+          build_google_query(model_id, messages, tools)
+        else
+          # Anthropic and OpenAI have the same query format
+          build_messages_query(model_id, messages, tools)
+        end
+      end
+
+      # Builds an OpenAI-compatible query (used for Anthropic and OpenAI providers).
+      def build_messages_query(model_id, messages, tools)
+        query = { model: model_id, messages: messages }
+        unless tools.empty?
+          query[:tools] = tools.values.map do |t|
+            { name: t.name, description: t.description, parameters: t.params_schema }
+          end
+        end
+        query
+      end
+
+      # Builds a Google-native query with contents/systemInstruction structure.
+      def build_google_query(model_id, messages, tools)
+        system_msgs = messages.select { |m| m[:role] == "system" }
+        content_msgs = messages.reject { |m| m[:role] == "system" }
+
+        query = {
+          model: model_id,
+          contents: content_msgs.map do |m|
+            google_role = m[:role] == "assistant" ? "model" : m[:role]
+            { role: google_role, parts: [{ text: m[:content] }] }
+          end
+        }
+
+        if system_msgs.any?
+          system_text = system_msgs.map { |m| m[:content] }.join("\n")
+          query[:systemInstruction] = { parts: [{ text: system_text }] }
+        end
+
+        unless tools.empty?
+          query[:tools] = tools.values.map do |t|
+            { name: t.name, description: t.description, parameters: t.params_schema }
+          end
+        end
+
+        query
+      end
+    end
+  end
+end

data/lib/crystil.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "crystil/version"
+require_relative "crystil/errors"
+require_relative "crystil/config"
+require_relative "crystil/sentinel"
+require_relative "crystil/attribution"
+require_relative "crystil/collector"
+require_relative "crystil/wrappers/base"
+require_relative "crystil/wrappers/openai"
+require_relative "crystil/wrappers/anthropic"
+require_relative "crystil/wrappers/google"
+require_relative "crystil/wrappers/geminiai"
+require_relative "crystil/wrappers/ruby_llm"
+require_relative "crystil/wrappers/groq"
+require_relative "crystil/api/base"
+require_relative "crystil/api/sentinel"
+require_relative "crystil/api/workflows"
+require_relative "crystil/api/invocation"
+require_relative "crystil/api/workflow"
+require_relative "crystil/client"
+
+# Crystil - Cost visibility for AI agents
+#
+# Crystil is a lightweight infrastructure layer that gives AI teams
+# real-time visibility into the true costs of deploying agents.
+#
+# @example Basic usage with OpenAI
+#   require 'openai'
+#   require 'crystil'
+#
+#   openai = OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
+#   crystil = Crystil::Client.new(api_key: ENV['CRYSTIL_API_KEY'])
+#   crystil.openai.register(openai)
+#
+#   # Use OpenAI normally - analytics tracked automatically
+#   response = openai.chat(
+#     parameters: {
+#       model: "gpt-4",
+#       messages: [{ role: "user", content: "Hello!" }]
+#     }
+#   )
+#
+# @example With attribution
+#   crystil.attribution(
+#     parent_id: "user-123",
+#     parent_name: "John Doe"
+#   )
+#
+# @see https://developers.crystil.com
+module Crystil
+end

data/sig/crystil/api/base.rbs

@@ -0,0 +1,24 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  module API
+    class Base
+      @original_api_url: String
+      @api_url: String
+      @api_key: String
+      @timeout: Numeric
+
+      def initialize: (String api_url, String api_key, Numeric timeout) -> void
+
+      private
+      def get: (String path) -> untyped
+      def post: (String path, ?Hash[Symbol, untyped]? body) -> untyped
+      def put: (String path, ?Hash[Symbol, untyped]? body) -> untyped
+      def delete: (String path) -> untyped
+      def request: (Symbol method, String path, ?Hash[Symbol, untyped]? body) -> untyped
+      def build_request: (Symbol method, URI::Generic uri, Hash[Symbol, untyped]? body) -> (Net::HTTP::Delete | Net::HTTP::Get | Net::HTTP::Post | Net::HTTP::Put)
+      def handle_response: (Net::HTTPResponse response) -> untyped
+      def parse_json_response: (String? body) -> untyped
+    end
+  end
+end

data/sig/crystil/api/invocation.rbs

@@ -0,0 +1,16 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  module API
+    class Invocation < Base
+      @attribution: Hash[Symbol, untyped]?
+
+      def initialize: (String api_url, String api_key, Numeric timeout) -> void
+      def attribution: (parent_id: String, ?parent_name: String?, ?subsidiary_id: String?, ?subsidiary_name: String?) -> self
+      def summary: (String workflow_uuid, date_start: (Date | Time | String), ?date_end: (Date | Time | String)?) -> untyped
+
+      private
+      def format_date: ((Date | Time | String) date) -> String
+    end
+  end
+end

data/sig/crystil/api/sentinel.rbs

@@ -0,0 +1,9 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  module API
+    class Sentinel < Base
+      def relevance_intercept: (Hash[Symbol, untyped] payload) -> untyped
+    end
+  end
+end

data/sig/crystil/api/workflow.rbs

@@ -0,0 +1,15 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  module API
+    class Workflow < Base
+      @uuid: String
+
+      def initialize: (String uuid, String api_url, String api_key, Numeric timeout) -> void
+      def details: -> untyped
+      def update: (label: String) -> untyped
+      def destroy: -> untyped
+      def invocation: -> Crystil::API::Invocation
+    end
+  end
+end

data/sig/crystil/api/workflows.rbs

@@ -0,0 +1,16 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  module API
+    class Workflows < Base
+      @invocation: Crystil::API::Invocation
+
+      def list: -> untyped
+      def create: (name: String, ?description: String?) -> untyped
+      def details: (String uuid) -> untyped
+      def update: (String uuid, label: String) -> untyped
+      def destroy: (String uuid) -> untyped
+      def invocation: -> Crystil::API::Invocation
+    end
+  end
+end

data/sig/crystil/attribution.rbs

@@ -0,0 +1,17 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  class Attribution
+    attr_reader parent_id: String
+    attr_reader parent_name: String?
+    attr_reader subsidiary_id: String?
+    attr_reader subsidiary_name: String?
+    def initialize: (parent_id: String, ?parent_name: String?, ?subsidiary_id: String?, ?subsidiary_name: String?) -> void
+    def to_h: -> Hash[Symbol, untyped]
+
+    private
+    def validate_parent_id!: (untyped value) -> String
+    def validate_string_length!: (untyped value, String field_name) -> String?
+    def validate_subsidiary_requirements!: -> void
+  end
+end

data/sig/crystil/client.rbs

@@ -0,0 +1,29 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  class Client
+    @openai: Crystil::Wrappers::OpenAI
+    @anthropic: Crystil::Wrappers::Anthropic
+    @google: Crystil::Wrappers::Google
+    @geminiai: Crystil::Wrappers::GeminiAI
+    @ruby_llm: Crystil::Wrappers::RubyLLM
+    @groq: Crystil::Wrappers::Groq
+    @workflows: Crystil::API::Workflows
+
+    attr_reader config: Crystil::Config
+    attr_reader collector: Crystil::Collector
+    attr_reader sentinel: Crystil::Sentinel
+
+    def initialize: (?api_key: String?, ?collector_url: String?, ?api_url: String?, ?timeout: Numeric?) -> void
+    def openai: -> Crystil::Wrappers::OpenAI
+    def anthropic: -> Crystil::Wrappers::Anthropic
+    def google: -> Crystil::Wrappers::Google
+    def geminiai: -> Crystil::Wrappers::GeminiAI
+    def ruby_llm: -> Crystil::Wrappers::RubyLLM
+    def groq: -> Crystil::Wrappers::Groq
+    def attribution: (parent_id: String, ?parent_name: String?, ?subsidiary_id: String?, ?subsidiary_name: String?) -> self
+    def new_transaction: -> self
+    def workflows: -> Crystil::API::Workflows
+    def shutdown: -> void
+  end
+end

data/sig/crystil/collector.rbs

@@ -0,0 +1,20 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  class Collector
+    DEFAULT_MAX_RETRIES: Integer
+    RETRY_DELAY: Integer
+    @config: Crystil::Config
+    # Concurrent::ThreadPoolExecutor — no upstream signatures available.
+    @executor: untyped
+
+    def initialize: (Crystil::Config config) -> void
+    def submit_async: (Hash[Symbol, untyped] payload) -> void
+    def submit: (Hash[Symbol, untyped] payload) -> untyped
+    def shutdown: -> void
+
+    private
+    def submit_with_retry: (Hash[Symbol, untyped] payload, ?Integer attempt) -> untyped
+    def post_to_collector: (Hash[Symbol, untyped] payload) -> untyped
+  end
+end

data/sig/crystil/config.rbs

@@ -0,0 +1,33 @@
+# Starter signatures generated by typeprof + hand-refined; see CLAUDE.md
+# "Code style: type signatures (RBS)" for the refinement convention.
+module Crystil
+  class Config
+    # Concurrent::AtomicReference[T] — no `concurrent-ruby` signatures for
+    # that class are shipped in the public rbs_collection, so falls back to
+    # `untyped`. Refine once we add a hand-rolled stub or upstream sig.
+    @attribution: untyped
+    @tx_uuid: untyped
+    @raise_if_irrelevant: untyped
+    @secs_irrelevant_request_timeout: untyped
+
+    attr_reader api_key: String
+    attr_reader collector_url: String
+    attr_reader api_url: String
+    attr_reader timeout: Numeric
+    attr_reader version: String
+
+    def initialize: (?api_key: String?, ?collector_url: String?, ?api_url: String?, ?timeout: Numeric?) -> void
+    def attribution: -> Crystil::Attribution?
+    def attribution=: (Crystil::Attribution? value) -> void
+    def tx_uuid: -> String
+    def tx_uuid=: (String value) -> void
+    def raise_if_irrelevant: -> bool
+    def raise_if_irrelevant=: (bool value) -> void
+    def secs_irrelevant_request_timeout: -> Numeric
+    def secs_irrelevant_request_timeout=: (Numeric value) -> void
+    def new_transaction: -> String
+
+    private
+    def nonempty_env: (String name) -> String?
+  end
+end