crystil 0.5.0

data/lib/crystil/collector.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "concurrent"
+
+module Crystil
+  # Handles asynchronous submission of analytics to Crystil collector
+  class Collector
+    DEFAULT_MAX_RETRIES = 3
+    RETRY_DELAY = 1 # seconds
+
+    def initialize(config)
+      @config = config
+      @executor = Concurrent::ThreadPoolExecutor.new(
+        min_threads: 1,
+        max_threads: 5,
+        max_queue: 100,
+        fallback_policy: :discard
+      )
+    end
+
+    # Submit analytics payload asynchronously
+    def submit_async(payload)
+      @executor.post do
+        submit_with_retry(payload)
+      rescue StandardError => e
+        warn "Crystil: Failed to submit analytics: #{e.message}"
+      end
+    end
+
+    # Submit analytics payload synchronously (for testing)
+    def submit(payload)
+      submit_with_retry(payload)
+    end
+
+    # Gracefully shutdown the collector
+    def shutdown
+      @executor.shutdown
+      @executor.wait_for_termination(5)
+    end
+
+    private
+
+    def submit_with_retry(payload, attempt = 1)
+      response = post_to_collector(payload)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise APIError.new(
+          "Collector request failed: #{response.code} #{response.message}",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      end
+
+      response
+    rescue StandardError => e
+      raise e unless attempt < DEFAULT_MAX_RETRIES
+
+      sleep(RETRY_DELAY * attempt)
+      submit_with_retry(payload, attempt + 1)
+    end
+
+    def post_to_collector(payload)
+      uri = URI.parse(@config.collector_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      # Configure SSL to use system certificates
+      if http.use_ssl?
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.cert_store = OpenSSL::X509::Store.new
+        http.cert_store.set_default_paths
+      end
+
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
+
+      request = Net::HTTP::Post.new("/rec")
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "crystil-ruby/#{@config.version}"
+      request.body = JSON.generate(payload)
+
+      http.request(request)
+    end
+  end
+end

data/lib/crystil/config.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Crystil
+  # Thread-safe configuration for Crystil client
+  class Config
+    attr_reader :api_key, :collector_url, :api_url, :timeout, :version
+
+    def initialize(api_key: nil, collector_url: nil, api_url: nil, timeout: nil)
+      @api_key = api_key
+      # URL precedence: constructor arg > CRYSTIL_*_URL_BASE env var > hardcoded
+      # prod default. Matches the JS SDK so an integration-test run pointed at
+      # staging or a local backend only requires setting the env vars in
+      # `.env` — no spec changes needed.
+      @collector_url = collector_url ||
+                       nonempty_env("CRYSTIL_COLLECTOR_URL_BASE") ||
+                       "https://collector.crystil.com"
+      @api_url = api_url ||
+                 nonempty_env("CRYSTIL_API_URL_BASE") ||
+                 "https://api.crystil.com"
+      @timeout = timeout || 5
+      @version = Crystil::VERSION
+      @attribution = Concurrent::AtomicReference.new(nil)
+      @tx_uuid = Concurrent::AtomicReference.new(SecureRandom.uuid)
+      @raise_if_irrelevant = Concurrent::AtomicReference.new(false)
+      @secs_irrelevant_request_timeout = Concurrent::AtomicReference.new(5)
+    end
+
+    def attribution
+      @attribution.get
+    end
+
+    def attribution=(value)
+      @attribution.set(value)
+    end
+
+    def tx_uuid
+      @tx_uuid.get
+    end
+
+    def tx_uuid=(value)
+      @tx_uuid.set(value)
+    end
+
+    def raise_if_irrelevant
+      @raise_if_irrelevant.get
+    end
+
+    def raise_if_irrelevant=(value)
+      @raise_if_irrelevant.set(value)
+    end
+
+    def secs_irrelevant_request_timeout
+      @secs_irrelevant_request_timeout.get
+    end
+
+    def secs_irrelevant_request_timeout=(value)
+      @secs_irrelevant_request_timeout.set(value)
+    end
+
+    def new_transaction
+      @tx_uuid.set(SecureRandom.uuid)
+    end
+
+    private
+
+    # Returns ENV[name] unless it's missing or empty. We can't use the JS-style
+    # `ENV[name] || default` because Ruby treats empty strings as truthy — and
+    # the `.env.example` ships with blank values for the URL keys, so naïve
+    # truthiness would route every request to "".
+    def nonempty_env(name)
+      value = ENV.fetch(name, nil)
+      return nil if value.nil? || value.empty?
+
+      value
+    end
+  end
+end

data/lib/crystil/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Crystil
+  # Base error class for all Crystil errors
+  class Error < StandardError; end
+
+  # Raised when API key is missing
+  class MissingAPIKeyError < Error
+    def initialize(msg = "API key is missing. Set CRYSTIL_API_KEY environment variable or pass api_key parameter.")
+      super
+    end
+  end
+
+  # Raised when validation fails
+  class ValidationError < Error; end
+
+  # Raised when client registration fails
+  class RegistrationError < Error; end
+
+  # Raised when API request fails
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  class CrystilRequestInterceptedError < Error; end
+
+  # Raised when a streaming response ends without the expected terminal event
+  class StreamError < Error; end
+end

data/lib/crystil/sentinel.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Crystil
+  class Sentinel
+    def initialize(config)
+      @config = config
+    end
+
+    def raise_if_irrelevant(enabled: true)
+      raise TypeError, "enabled must be a bool" unless [true, false].include?(enabled)
+
+      @config.raise_if_irrelevant = enabled
+      self
+    end
+
+    # Intentional explicit `set_*` verb prefix — matches JS/Python SDK naming
+    # so callers porting code between SDKs see the same surface. See CLAUDE.md
+    # "Python SDK is the source of truth" / known divergences.
+    def set_secs_irrelevant_request_timeout(timeout) # rubocop:disable Naming/AccessorMethodName
+      raise TypeError, "timeout must be a Numeric" unless timeout.is_a?(Numeric)
+      raise ArgumentError, "timeout must be greater than 0" unless timeout.positive?
+
+      @config.secs_irrelevant_request_timeout = timeout
+      self
+    end
+
+    def raise_if_irrelevant!(title:, request:, provider: nil, version: nil)
+      return unless @config.raise_if_irrelevant
+
+      begin
+        relevant, reason = make_relevance_intercept_request(
+          title: title,
+          request: request,
+          provider: provider,
+          version: version
+        )
+      rescue StandardError
+        return nil
+      end
+
+      raise CrystilRequestInterceptedError, (reason || "Irrelevant request blocked.") unless relevant
+    end
+
+    private
+
+    def make_relevance_intercept_request(title:, request:, provider: nil, version: nil)
+      payload = {
+        attribution: @config.attribution&.to_h,
+        conversation: {
+          client: {
+            provider: provider,
+            title: title,
+            version: version
+          },
+          request: normalize_request(request)
+        },
+        meta: {
+          sdk: {
+            client: "ruby",
+            version: @config.version
+          }
+        }
+      }
+
+      api = API::Sentinel.new(@config.api_url, @config.api_key, @config.secs_irrelevant_request_timeout)
+      response = api.relevance_intercept(payload) || {}
+
+      relevant = response.key?("relevant") ? response["relevant"] : true
+      reason = relevant ? nil : (response["reason"] || "Irrelevant request blocked.")
+
+      [relevant, reason]
+    end
+
+    def normalize_request(request)
+      # Remove Procs before JSON creation since the
+      # procs or methods will fail for normalization.
+      # We know that OpenAI sends a proc on their
+      # request, so this is mostly for that.
+      cleaned = remove_procs(request)
+      json_obj = JSON.generate(cleaned)
+      JSON.parse(json_obj)
+    rescue StandardError
+      request
+    end
+
+    def remove_procs(obj)
+      case obj
+      when Hash
+        obj.transform_values { |v| remove_procs(v) }
+      when Array
+        obj.map { |v| remove_procs(v) }
+      when Proc, Method
+        true
+      else
+        # Return true object for any callable object; otherwise return obj.
+        obj.respond_to?(:call) || obj
+      end
+    end
+  end
+end

data/lib/crystil/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Crystil
+  VERSION = "0.5.0"
+end

data/lib/crystil/wrappers/anthropic.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Crystil
+  module Wrappers
+    # Wrapper for Anthropic Ruby client
+    class Anthropic
+      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 messages method
+        wrap_messages_method(client)
+
+        client
+      end
+
+      private
+
+      def validate_client!(client)
+        return if client.respond_to?(:messages)
+
+        raise RegistrationError, "Client does not appear to be a valid Anthropic client (missing messages method)"
+      end
+
+      def wrap_messages_method(client)
+        # Get the messages resource
+        messages_resource = client.messages
+
+        # Store references on the messages resource (needed for Base module)
+        messages_resource.instance_variable_set(:@crystil_config, client.instance_variable_get(:@crystil_config))
+        messages_resource.instance_variable_set(:@crystil_collector, client.instance_variable_get(:@crystil_collector))
+        messages_resource.instance_variable_set(:@crystil_sentinel, client.instance_variable_get(:@crystil_sentinel))
+
+        # Store the original create method
+        original_create = messages_resource.method(:create)
+
+        # Wrap the create method
+        messages_resource.define_singleton_method(:create) do |*args, **kwargs, &block|
+          # Include Base module methods
+          extend Base unless singleton_class.include?(Base)
+
+          start_time = Time.now
+          version = defined?(::Anthropic::VERSION) ? ::Anthropic::VERSION : nil
+
+          # Extract parameters for sentinel and analytics
+          params = kwargs.any? ? kwargs : (args.first || {})
+          sentinel = instance_variable_get(:@crystil_sentinel)
+          sentinel&.raise_if_irrelevant!(
+            title: ANTHROPIC_CLIENT_TITLE,
+            request: params,
+            version: version
+          )
+
+          # Call original method
+          response = if kwargs.any?
+                       original_create.call(**kwargs, &block)
+                     else
+                       original_create.call(*args, &block)
+                     end
+
+          # Submit analytics
+          crystil_submit_analytics(
+            method: :create,
+            args: args,
+            kwargs: params,
+            response: response,
+            start_time: start_time,
+            end_time: Time.now,
+            title: ANTHROPIC_CLIENT_TITLE,
+            version: version
+          )
+
+          response
+        rescue CrystilRequestInterceptedError => e
+          # We don't want to send intercepts to collector
+          raise e
+        rescue StandardError => e
+          params = kwargs.any? ? kwargs : (args.first || {})
+
+          crystil_submit_error_analytics(
+            method: :create,
+            args: args,
+            kwargs: params,
+            error: e,
+            start_time: start_time,
+            end_time: Time.now,
+            title: ANTHROPIC_CLIENT_TITLE,
+            version: version
+          )
+
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/crystil/wrappers/base.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Crystil
+  module Wrappers
+    # Base functionality for all provider wrappers
+    module Base
+      def crystil_wrap_method(method_name, _provider_name)
+        return if method(method_name).source_location&.first&.include?("crystil")
+
+        original_method = instance_method(method_name)
+
+        define_method(method_name) do |*args, **kwargs, &block|
+          start_time = Time.now
+
+          # Call original method
+          response = original_method.bind(self).call(*args, **kwargs, &block)
+
+          # Submit analytics asynchronously
+          crystil_submit_analytics(
+            method: method_name,
+            args: args,
+            kwargs: kwargs,
+            response: response,
+            start_time: start_time,
+            end_time: Time.now
+          )
+
+          response
+        rescue StandardError => e
+          # Submit error analytics
+          crystil_submit_error_analytics(
+            method: method_name,
+            args: args,
+            kwargs: kwargs,
+            error: e,
+            start_time: start_time,
+            end_time: Time.now
+          )
+
+          raise e
+        end
+      end
+
+      def crystil_submit_analytics(method:, args:, kwargs:, response:, start_time:,
+                                   end_time:, provider: nil, title: nil, version: nil,
+                                   status: "succeeded", exception: nil)
+        collector = instance_variable_get(:@crystil_collector)
+        config = instance_variable_get(:@crystil_config)
+
+        return unless collector && config
+
+        payload = build_payload(
+          query: extract_query(method, args, kwargs),
+          response: extract_response(response),
+          start_time: start_time,
+          end_time: end_time,
+          config: config,
+          status: status,
+          provider: provider,
+          title: title,
+          version: version,
+          exception: exception
+        )
+
+        collector.submit_async(payload)
+      end
+
+      # Submit a failed-call payload to the collector. `response:` is optional —
+      # when omitted, the default `{ error:, class: }` shape is used. Wrappers
+      # that preserve richer data on error (e.g. Groq's streaming wrapper
+      # merging accumulated chunks with error info via build_error_response)
+      # pass it explicitly; the backend extractor reads whatever fields it can
+      # from the supplied hash and falls back gracefully on missing keys.
+      def crystil_submit_error_analytics(method:, args:, kwargs:, error:, start_time:,
+                                         end_time:, provider: nil, title: nil, version: nil,
+                                         response: nil)
+        crystil_submit_analytics(
+          method: method,
+          args: args,
+          kwargs: kwargs,
+          response: response || { error: error.message, class: error.class.name },
+          start_time: start_time,
+          end_time: end_time,
+          provider: provider,
+          title: title,
+          version: version,
+          status: "failed",
+          exception: error.message
+        )
+      end
+
+      def crystil_merge_streaming_chunk(accumulated, chunk)
+        chunk.each do |key, value|
+          if accumulated.key?(key)
+            case accumulated[key]
+            when Hash
+              crystil_merge_streaming_chunk(accumulated[key], value) if value.is_a?(Hash)
+            when Array
+              # Concatenate arrays (matches Python SDK behavior: data[key].extend(chunk_value))
+              accumulated[key].concat(value) if value.is_a?(Array)
+            else
+              accumulated[key] = value
+            end
+          else
+            accumulated[key] = value
+          end
+        end
+        accumulated
+      end
+
+      def crystil_normalize_openai_chunk(chunk)
+        # Normalize OpenAI streaming chunks to match Python SDK format
+        # Ensure delta objects have all keys present with null values
+        return chunk unless chunk.is_a?(Hash)
+
+        if chunk["choices"].is_a?(Array)
+          chunk["choices"].each do |choice|
+            next unless choice.is_a?(Hash) && choice.key?("delta")
+
+            delta = choice["delta"]
+            next unless delta.is_a?(Hash)
+
+            # Add missing keys with nil values to match Python SDK
+            delta["role"] ||= nil unless delta.key?("role")
+            delta["content"] ||= nil unless delta.key?("content")
+            delta["refusal"] ||= nil unless delta.key?("refusal")
+            delta["tool_calls"] ||= nil unless delta.key?("tool_calls")
+            delta["function_call"] ||= nil unless delta.key?("function_call")
+          end
+        end
+
+        chunk
+      end
+
+      private
+
+      def extract_query(_method, _args, kwargs)
+        # Deep copy to avoid mutation issues
+        query = deep_copy(kwargs)
+
+        # Normalize stream parameter: convert Proc to boolean true
+        # This ensures streaming requests are properly serialized to JSON
+        query[:stream] = true if query.is_a?(Hash) && query[:stream].is_a?(Proc)
+
+        query
+      rescue StandardError
+        {}
+      end
+
+      def extract_response(response)
+        case response
+        when Hash, Array
+          deep_copy(response)
+        when String
+          { text: response }
+        else
+          # Try various serialization methods
+          if response.respond_to?(:as_json)
+            deep_copy(response.as_json)
+          elsif response.respond_to?(:to_h)
+            deep_copy(response.to_h)
+          elsif response.respond_to?(:to_hash)
+            deep_copy(response.to_hash)
+          else
+            # Extract instance variables for objects without serialization methods
+            extract_instance_variables(response)
+          end
+        end
+      rescue StandardError => e
+        # If extraction fails, try to provide useful debug info
+        { raw: response.to_s, error: e.message }
+      end
+
+      def extract_instance_variables(obj)
+        result = {}
+        obj.instance_variables.each do |var|
+          key = var.to_s.delete("@").to_sym
+          value = obj.instance_variable_get(var)
+          result[key] = serialize_value(value)
+        end
+        result
+      end
+
+      def serialize_value(value)
+        case value
+        when Hash
+          value.transform_values { |v| serialize_value(v) }
+        when Array
+          value.map { |v| serialize_value(v) }
+        when String, Numeric, TrueClass, FalseClass, NilClass
+          value
+        else
+          # Recursively extract instance variables for nested objects
+          if value.respond_to?(:instance_variables)
+            extract_instance_variables(value)
+          else
+            value.to_s
+          end
+        end
+      end
+
+      def deep_copy(obj)
+        Marshal.load(Marshal.dump(obj))
+      rescue StandardError
+        begin
+          obj.dup
+        rescue StandardError
+          obj
+        end
+      end
+
+      # Build the payload that is sent to the collector API which then sends the payload
+      # to the backend.
+      # - conversion.client - Routes the payload to the correct service
+      # in the backend.  So, the title and provider values are known values.  (e.g google,
+      # openai, and anthropic) are common title values.
+      # - conversion.query - Holds the request information.
+      # - conversion.response - Holds the response from the LLM.  This is different for each LLM,
+      # and the different services handle them on the backend.
+      def build_payload(query:, response:, start_time:, end_time:, config:, status:,
+                        provider: nil, title: nil, version: nil, exception: nil)
+        {
+          attribution: config.attribution&.to_h,
+          conversation: {
+            client: {
+              provider: provider,
+              title: title,
+              version: version
+            },
+            query: query,
+            response: response
+          },
+          meta: {
+            api: {
+              key: config.api_key
+            },
+            fnfg: {
+              status: status,
+              exc: exception
+            },
+            sdk: {
+              client: "ruby",
+              version: config.version
+            }
+          },
+          time: {
+            start: start_time.to_f,
+            end: end_time.to_f
+          },
+          tx: {
+            uuid: config.tx_uuid
+          }
+        }
+      end
+    end
+  end
+end

data/lib/crystil/wrappers/constants.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Crystil
+  module Wrappers
+    # Client title constants for analytics
+    OPENAI_CLIENT_TITLE = "openai"
+    ANTHROPIC_CLIENT_TITLE = "anthropic"
+    GOOGLE_CLIENT_TITLE = "google"
+    RUBY_LLM_PROVIDER = "ruby_llm"
+    GROQ_PROVIDER = "groq"
+  end
+end