coolhand 0.1.5 → 0.3.0

data/lib/coolhand.rb

@@ -1,4 +1,111 @@
 # frozen_string_literal: true
 
-# Main entry point for the Coolhand gem
-require_relative "coolhand/ruby"
+require "uri"
+require "faraday"
+require "securerandom"
+require "json"
+require "base64"
+
+require_relative "coolhand/version"
+require_relative "coolhand/configuration"
+require_relative "coolhand/collector"
+require_relative "coolhand/base_interceptor"
+require_relative "coolhand/net_http_interceptor"
+require_relative "coolhand/api_service"
+require_relative "coolhand/logger_service"
+require_relative "coolhand/feedback_service"
+require_relative "coolhand/webhook_interceptor"
+
+# The main module for the Coolhand gem.
+# It provides the configuration interface and initializes the patching.
+module Coolhand
+  class Error < StandardError; end
+
+  # Class-level instance variables to hold the configuration
+  @configuration = Configuration.new
+
+  class << self
+    attr_reader :configuration
+
+    # Reset configuration to defaults (mainly for testing)
+    def reset_configuration!
+      @configuration = Configuration.new
+      Thread.current[:coolhand_capture_override] = nil
+    end
+
+    # Provides a block to configure the gem.
+    #
+    # Example:
+    #   Coolhand.configure do |config|
+    #     config.environment = 'development'
+    #     config.silent = false
+    #     config.api_key = "xxx-yyy-zzz"
+    #     config.intercept_addresses = ["openai.com", "api.anthropic.com"]
+    #   end
+    def configure
+      yield(configuration)
+
+      configuration.validate!
+
+      NetHttpInterceptor.patch!
+
+      log "✅ Coolhand ready - will log inference calls on monitored URIs"
+    end
+
+    def capture
+      unless block_given?
+        log "❌ Coolhand Error: Method .capture requires block."
+        return
+      end
+
+      patched = NetHttpInterceptor.patched?
+
+      NetHttpInterceptor.patch!
+
+      yield
+    ensure
+      NetHttpInterceptor.unpatch! unless patched
+    end
+
+    def without_capture
+      previous = Thread.current[:coolhand_capture_override]
+      Thread.current[:coolhand_capture_override] = false
+      yield
+    ensure
+      Thread.current[:coolhand_capture_override] = previous
+    end
+
+    def with_capture
+      previous = Thread.current[:coolhand_capture_override]
+      Thread.current[:coolhand_capture_override] = true
+      yield
+    ensure
+      Thread.current[:coolhand_capture_override] = previous
+    end
+
+    # A simple logger that respects the 'silent' configuration option.
+    def log(message)
+      return if configuration.silent
+
+      puts "COOLHAND: #{message}"
+    end
+
+    # Creates a new FeedbackService instance
+    def feedback_service
+      FeedbackService.new
+    end
+
+    # Creates a new LoggerService instance
+    def logger_service
+      LoggerService.new
+    end
+
+    def required_field?(value)
+      return false if value.nil?
+      return false if value.respond_to?(:empty?) && value.empty?
+      return false if value.to_s.strip.empty?
+
+      true
+    end
+  end
+end

metadata

@@ -1,18 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Carroll
 - Yaroslav Malyk
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-09 00:00:00.000000000 Z
-dependencies: []
-description: A Ruby gem to automatically monitor and log external LLM requests. It
-  patches Net::HTTP to capture request and response data.
+date: 2026-05-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Automatically intercept and log LLM requests from Ruby applications.
+  Supports OpenAI, official Anthropic gem, ruby-anthropic gem, and other Faraday-based
+  libraries. Features dual interceptor architecture, streaming support, thread-safe
+  operation, and automatic duplicate request prevention.
 email:
 - mc@coolhandlabs.com
 executables: []
@@ -24,20 +39,28 @@ files:
 - ".rubocop.yml"
 - ".simplecov"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE
 - README.md
 - Rakefile
 - coolhand-ruby.gemspec
+- docs/anthropic.md
 - docs/elevenlabs.md
 - lib/coolhand.rb
-- lib/coolhand/ruby.rb
-- lib/coolhand/ruby/api_service.rb
-- lib/coolhand/ruby/collector.rb
-- lib/coolhand/ruby/configuration.rb
-- lib/coolhand/ruby/feedback_service.rb
-- lib/coolhand/ruby/interceptor.rb
-- lib/coolhand/ruby/logger_service.rb
-- lib/coolhand/ruby/version.rb
+- lib/coolhand/api_service.rb
+- lib/coolhand/base_interceptor.rb
+- lib/coolhand/collector.rb
+- lib/coolhand/configuration.rb
+- lib/coolhand/default_exclude_api_patterns.yml
+- lib/coolhand/default_intercept_addresses.yml
+- lib/coolhand/feedback_service.rb
+- lib/coolhand/logger_service.rb
+- lib/coolhand/net_http_interceptor.rb
+- lib/coolhand/open_ai/batch_result_processor.rb
+- lib/coolhand/open_ai/webhook_validator.rb
+- lib/coolhand/version.rb
+- lib/coolhand/vertex/batch_result_processor.rb
+- lib/coolhand/webhook_interceptor.rb
 - sig/coolhand/ruby.rbs
 homepage: https://coolhandlabs.com/
 licenses:
@@ -46,9 +69,8 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://coolhandlabs.com/
   source_code_uri: https://github.com/Coolhand-Labs/coolhand-ruby
-  changelog_uri: https://github.com/Coolhand-Labs/coolhand-ruby
+  changelog_uri: https://github.com/Coolhand-Labs/coolhand-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -63,8 +85,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
-summary: Intercepts and logs OpenAI API calls from a Ruby application.
+summary: Monitor and log LLM API calls from OpenAI, Anthropic, and other providers
+  to Coolhand analytics.
 test_files: []

data/lib/coolhand/ruby/api_service.rb

@@ -1,211 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "uri"
-require "json"
-require_relative "collector"
-
-module Coolhand
-  module Ruby
-    class ApiService
-      BASE_URI = "https://coolhandlabs.com/api"
-
-      attr_reader :api_endpoint
-
-      def initialize(endpoint_path)
-        @api_endpoint = "#{BASE_URI}/#{endpoint_path}"
-      end
-
-      def configuration
-        Coolhand.configuration
-      end
-
-      def api_key
-        configuration.api_key
-      end
-
-      def silent
-        configuration.silent
-      end
-
-      protected
-
-      # Add collector field to the data being sent
-      def add_collector_to_data(data, collection_method = nil)
-        data.merge(collector: Collector.get_collector_string(collection_method))
-      end
-
-      def create_request_options(_payload)
-        {
-          "Content-Type" => "application/json",
-          "X-API-Key" => api_key
-        }
-      end
-
-      def send_request(payload, success_message)
-        uri = URI.parse(@api_endpoint)
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = (uri.scheme == "https")
-
-        request = Net::HTTP::Post.new(uri.request_uri)
-        headers = create_request_options(payload)
-        headers.each do |key, value|
-          # Ensure header values are UTF-8 encoded
-          encoded_value = value.is_a?(String) ? value.dup.force_encoding("UTF-8") : value
-          request[key] = encoded_value
-        end
-
-        # Clean payload and ensure UTF-8 encoding before JSON generation
-        cleaned_payload = sanitize_payload_for_json(payload)
-        json_body = JSON.generate(cleaned_payload)
-
-        # Ensure the request body is properly encoded as UTF-8
-        request.body = json_body.force_encoding("UTF-8")
-
-        begin
-          response = http.request(request)
-
-          if response.is_a?(Net::HTTPSuccess)
-            result = JSON.parse(response.body, symbolize_names: true)
-            log success_message
-            result
-          else
-            body = response.body.force_encoding("UTF-8") if response.body
-            puts "❌ Request failed: #{response.code} - #{body}"
-            nil
-          end
-        rescue StandardError => e
-          log "❌ Request error: #{e.message}"
-          nil
-        end
-      end
-
-      def log(*args)
-        puts args.join(" ") unless silent
-      end
-
-      def log_separator
-        log("═" * 60) unless silent
-      end
-
-      def create_feedback(feedback, collection_method = nil)
-        feedback_with_collector = add_collector_to_data(feedback, collection_method)
-
-        payload = {
-          llm_request_log_feedback: feedback_with_collector
-        }
-
-        log_feedback_info(feedback)
-
-        result = send_request(
-          payload,
-          "✅ Successfully created feedback with ID: #{feedback[:llm_request_log_id] || 'N/A'}"
-        )
-
-        log_separator
-        result
-      end
-
-      def create_log(captured_data, collection_method = nil)
-        raw_request_with_collector = add_collector_to_data({ raw_request: captured_data }, collection_method)
-
-        payload = {
-          llm_request_log: raw_request_with_collector
-        }
-
-        log_request_info(captured_data)
-
-        result = send_request(
-          payload,
-          "✅ Successfully logged to API"
-        )
-
-        puts "✅ Successfully logged to API with ID: #{result[:id]}" if result && !silent
-
-        log_separator
-        result
-      end
-
-      # Filter list of known binary/problematic field names by service
-      BINARY_DATA_FILTERS = {
-        # ElevenLabs fields that contain binary audio data
-        elevenlabs: %w[
-          full_audio
-          audio
-          audio_data
-          raw_audio
-          audio_base64
-          voice_sample
-          audio_url
-        ],
-        # OpenAI fields that might contain binary data
-        openai: %w[
-          file_content
-          audio_data
-          image_data
-          binary_content
-        ]
-      }.freeze
-
-      private
-
-      # Get all filtered field names as a flat array
-      def filtered_field_names
-        @filtered_field_names ||= BINARY_DATA_FILTERS.values.flatten.map(&:downcase)
-      end
-
-      # Recursively sanitize payload to remove known problematic fields
-      def sanitize_payload_for_json(obj)
-        case obj
-        when Hash
-          obj.each_with_object({}) do |(key, value), sanitized|
-            key_str = key.to_s.downcase
-
-            # Skip if key matches any filtered field name
-            next if filtered_field_names.any? { |filter| key_str.include?(filter) }
-
-            sanitized[key] = sanitize_payload_for_json(value)
-          end
-        when Array
-          obj.map { |item| sanitize_payload_for_json(item) }
-        else
-          obj
-        end
-      rescue StandardError => e
-        log "⚠️ Warning: Error sanitizing payload: #{e.message}"
-        obj
-      end
-
-      def log_feedback_info(feedback)
-        return if silent
-
-        # Log the appropriate identifier based on what was provided
-        if feedback[:llm_request_log_id]
-          puts "\n📝 CREATING FEEDBACK for LLM Request Log ID: #{feedback[:llm_request_log_id]}"
-        elsif feedback[:llm_provider_unique_id]
-          puts "\n📝 CREATING FEEDBACK for Provider Unique ID: #{feedback[:llm_provider_unique_id]}"
-        else
-          puts "\n📝 CREATING FEEDBACK"
-        end
-
-        puts "👍/👎 Like: #{feedback[:like]}"
-
-        if feedback[:explanation]
-          explanation = feedback[:explanation]
-          truncated = explanation.length > 100 ? "#{explanation[0..99]}..." : explanation
-          puts "💭 Explanation: #{truncated}"
-        end
-
-        puts "📤 Sending to: #{@api_endpoint}"
-      end
-
-      def log_request_info(captured_data)
-        return if silent
-
-        puts "\n🎉 LOGGING OpenAI API Call #{@api_endpoint}"
-        puts captured_data
-        puts "📤 Sending to: #{@api_endpoint}"
-      end
-    end
-  end
-end

data/lib/coolhand/ruby/collector.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Coolhand
-  module Ruby
-    # Utility for generating collector identification string
-    module Collector
-      COLLECTION_METHODS = %w[manual auto-monitor].freeze
-
-      class << self
-        # Gets the collector identification string
-        # Format: "coolhand-ruby-X.Y.Z" or "coolhand-ruby-X.Y.Z-method"
-        # @param method [String, nil] Optional collection method suffix
-        # @return [String] Collector string identifying this SDK version and collection method
-        def get_collector_string(method = nil)
-          base = "coolhand-ruby-#{VERSION}"
-          method && COLLECTION_METHODS.include?(method) ? "#{base}-#{method}" : base
-        end
-      end
-    end
-  end
-end

data/lib/coolhand/ruby/configuration.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Coolhand
-  # Handles all configuration settings for the gem.
-  class Configuration
-    attr_accessor :api_key, :environment, :silent
-    attr_reader :intercept_addresses
-
-    def initialize
-      # Set defaults
-      @environment = "production"
-      @api_key = nil
-      @silent = false
-      @intercept_addresses = ["api.openai.com", "api.anthropic.com", "api.elevenlabs.io", ":generateContent"]
-    end
-
-    # Custom setter that preserves defaults when nil/empty array is provided
-    def intercept_addresses=(value)
-      return if value.nil? || (value.is_a?(Array) && value.empty?)
-
-      @intercept_addresses = value.is_a?(Array) ? value : [value]
-    end
-
-    def validate!
-      # Validate API Key after configuration
-      if api_key.nil?
-        Coolhand.log "❌ Coolhand Error: API Key is required. Please set it in the configuration."
-        raise Error, "API Key is required"
-      end
-
-      # Validate intercept_addresses after configuration
-      if intercept_addresses.nil? || intercept_addresses.empty?
-        Coolhand.log "❌ Coolhand Error: Intercept addresses cannot be empty. Please set it in the configuration."
-        raise Error, "Intercept addresses cannot be empty"
-      end
-    end
-  end
-end

data/lib/coolhand/ruby/feedback_service.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "api_service"
-
-module Coolhand
-  module Ruby
-    class FeedbackService < ApiService
-      def initialize
-        super("v2/llm_request_log_feedbacks")
-      end
-
-      def create_feedback(feedback)
-        super(feedback, "manual")
-      end
-    end
-  end
-end

data/lib/coolhand/ruby/interceptor.rb

@@ -1,119 +0,0 @@
-# frozen_string_literal: true
-
-module Coolhand
-  class Interceptor < Faraday::Middleware
-    ORIGINAL_METHOD_ALIAS = :coolhand_original_initialize
-
-    def self.patch!
-      return if @patched
-
-      @patched = true
-      Coolhand.log "📡 Monitoring outbound requests ..."
-
-      # Use prepend instead of alias_method to avoid conflicts with other gems
-      Faraday::Connection.prepend(Module.new do
-        def initialize(url = nil, options = nil, &block)
-          super
-
-          # Only add interceptor if it's not already present
-          use Coolhand::Interceptor unless @builder.handlers.any? { |h| h.klass == Coolhand::Interceptor }
-        end
-      end)
-
-      Coolhand.log "🔧 Setting up monitoring for Faraday ..."
-    end
-
-    def self.unpatch!
-      # NOTE: With prepend, there's no clean way to unpatch
-      # We'll mark it as unpatched so it can be re-patched
-      @patched = false
-      Coolhand.log "🔌 Faraday monitoring disabled ..."
-    end
-
-    def self.patched?
-      @patched
-    end
-
-    def call(env)
-      return super unless llm_api_request?(env)
-
-      Coolhand.log "🎯 INTERCEPTING OpenAI call #{env.url}"
-
-      call_data = build_call_data(env)
-      buffer = override_on_data(env)
-
-      process_complete_callback(env, buffer, call_data)
-    end
-
-    private
-
-    def llm_api_request?(env)
-      Coolhand.configuration.intercept_addresses.any? do |address|
-        env.url.to_s.include?(address)
-      end
-    end
-
-    def build_call_data(env)
-      {
-        id: SecureRandom.uuid,
-        timestamp: DateTime.now,
-        method: env.method,
-        url: env.url.to_s,
-        headers: sanitize_headers(env.request_headers),
-        request_body: parse_json(env.request_body),
-        response_body: nil,
-        response_headers: nil,
-        status_code: nil
-      }
-    end
-
-    def override_on_data(env)
-      buffer = +""
-      original_on_data = env.request.on_data
-      env.request.on_data = proc do |chunk, overall_received_bytes|
-        buffer << chunk
-
-        original_on_data&.call(chunk, overall_received_bytes)
-      end
-
-      buffer
-    end
-
-    def process_complete_callback(env, buffer, call_data)
-      @app.call(env).on_complete do |response_env|
-        if buffer.empty?
-          body = response_env.body
-        else
-          body = buffer
-          response_env.body = body
-        end
-
-        call_data[:response_body] = parse_json(body)
-        call_data[:response_headers] = sanitize_headers(response_env.request_headers)
-        call_data[:status_code] = response_env.status
-
-        Thread.new { Coolhand.logger_service.log_to_api(call_data) }
-      end
-    end
-
-    def parse_json(string)
-      JSON.parse(string)
-    rescue JSON::ParserError, TypeError
-      string
-    end
-
-    def sanitize_headers(headers)
-      sanitized = headers.transform_keys(&:to_s).dup
-
-      if sanitized["Authorization"]
-        sanitized["Authorization"] = sanitized["Authorization"].gsub(/Bearer .+/, "Bearer [REDACTED]")
-      end
-
-      %w[openai-api-key api-key].each do |key|
-        sanitized[key] = "[REDACTED]" if sanitized[key]
-      end
-
-      sanitized
-    end
-  end
-end