coolhand 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 193fc72a2e4d3c485584250f6f846ba97dbd02f55c357e8bf6f3f95641b669d5
-  data.tar.gz: 4523f4af59e1a81a7763edd5424e86bec7bd35eb40799af7ad253446d9c86bbe
+  metadata.gz: 4b8242433c93dec62fb833fc641c5917f6bb68c01e59e3061f2ac6300ec674c5
+  data.tar.gz: 7e6019bc86a3268df2ddebf4e0a9cfcabd32a72e3e8618a473c2035921aa0ff0
 SHA512:
-  metadata.gz: 6d65bfde6461c4f9676a2e0c64de863204e075abae9b762666119bad7676d21ff962e9aeafb3d0420e86ee9d00e0dcda9e266f99dbfc751b289e5e3c91e028cf
-  data.tar.gz: 48aa86e01741e1a93faec921e65e13a3d434740f91c0c564d22406279d15eab56f60f1aea1bebb5d9c5eb1095200c459b8e728cbd41cc118ee359edfb9eccec1
+  metadata.gz: 2255984a1e9238a8bfd1fedecf19aece7a552b25635873ec51803390ae679d206eb69dd0ff31d9df3d6169d78d9ba7503321eaf4bd048b2e59d3337b5c05758c
+  data.tar.gz: 44a5dc44c6a74385adf1e70057bf49f463c0401bea5f69b5850d697b414292fe0f9ebe208903f46325db80e0a638bf548c4a1dfcebe0d3b808f67a32b2167cdf

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.3] - 2024-10-23
+
+### ✨ New Features
+- **Collector Identifier** - Added collector field to all API calls to identify SDK version (format: `coolhand-ruby-X.Y.Z`)
+- **Collection Method Tracking** - Support for optional collection method suffix (`manual`, `auto-monitor`)
+
+### 🏗️ Internal Improvements
+- **Added Collector Module** - New `Coolhand::Ruby::Collector` module for generating SDK identification strings
+- **Updated ApiService** - Base service now automatically adds collector field to all API payloads
+- **Enhanced Logging** - Both LoggerService and FeedbackService now send collector information
+
 ## [0.1.2] - 2024-10-22
 
 ### 🔧 Configuration Improvements

data/README.md

@@ -24,7 +24,7 @@ gem 'coolhand'
 
 ```ruby
 # Add this configuration at the start of your application
-require 'coolhand'
+require 'coolhand/ruby'
 
 Coolhand.configure do |config|
   config.api_key = 'your_api_key_here'
@@ -52,7 +52,7 @@ end
 Collect feedback on LLM responses to improve model performance:
 
 ```ruby
-require 'coolhand'
+require 'coolhand/ruby'
 
 # Create feedback for an LLM response
 feedback_service = Coolhand::Ruby::FeedbackService.new(Coolhand.configuration)
@@ -164,7 +164,7 @@ end
 
 ```ruby
 require 'openai'
-require 'coolhand'
+require 'coolhand/ruby'
 
 # Configure Coolhand
 Coolhand.configure do |config|
@@ -190,7 +190,7 @@ puts response.dig("choices", 0, "message", "content")
 
 ```ruby
 require 'anthropic'
-require 'coolhand'
+require 'coolhand/ruby'
 
 # Configure Coolhand
 Coolhand.configure do |config|
@@ -210,6 +210,50 @@ puts response["content"]
 # Automatically logged to Coolhand!
 ```
 
+## Logging Inbound Webhooks
+
+For inbound webhooks (like audio transcripts or tool calls), the automatic interceptor won't capture them since they're incoming requests TO your application. In these cases, use the simple `forward_webhook` helper method:
+
+### Webhook Forwarding Example (Recommended)
+
+```ruby
+class WebhooksController < ApplicationController
+  def elevenlabs
+    raw_body = request.body.read
+    webhook_data = JSON.parse(raw_body)
+
+    # Forward to Coolhand with automatic field generation and binary filtering
+    Thread.new do
+      Coolhand.logger_service.forward_webhook(
+        webhook_body: webhook_data,        # Required: webhook payload
+        source: "elevenlabs",              # Required: service name
+        event_type: webhook_data["type"],  # Optional: e.g., post_call_transcription
+        headers: request.headers,          # Optional & recommended
+      )
+    end
+
+    render json: { status: "success" }
+  end
+end
+```
+
+**Required Parameters:**
+- `webhook_body` - The webhook payload (Hash or parsed JSON)
+- `source` - Service name (String, e.g., "elevenlabs", "stripe", "twilio")
+
+**Optional Parameters:**
+- `event_type` - Event type to append to URL (e.g., "post_call_transcription" → `webhook://elevenlabs/post_call_transcription`)
+- `headers` - Request headers (automatically sanitized)
+- `conversation_id`, `agent_id`, `metadata` - Custom fields for your tracking needs
+
+**Error Handling:**
+- **Silent mode = false**: Raises `ArgumentError` if required parameters are missing
+- **Silent mode = true**: Logs warning and returns `false` if required parameters are missing
+
+That's it! The `forward_webhook` method automatically:
+- ✅ Generates unique ID and timestamp
+- ✅ Filters out binary data (audio, images, etc.)
+
 ## What Gets Logged
 
 The monitor captures:
@@ -221,6 +265,24 @@ The monitor captures:
 
 Headers containing API keys are automatically sanitized for security.
 
+## Binary Data Filtering
+
+**Coolhand does not track or store binary data.** The gem automatically filters out:
+
+- Audio files and data (`audio`, `audio_data`, `full_audio`, `raw_audio`)
+- Image data (`image_data`, `image_content`)
+- File content (`file_content`, `binary_content`)
+- Base64 encoded data (`audio_base64`, `base64_data`)
+- Voice samples and audio URLs
+
+This ensures:
+- ✅ **Smaller payloads** - Only text and metadata are sent
+- ✅ **Faster processing** - No bandwidth wasted on binary data
+- ✅ **Privacy focused** - Audio/video content never leaves your infrastructure
+- ✅ **Clean logs** - Focus on conversational data, not media files
+
+The filtering is automatic and applies to all monitored API calls and webhook logging.
+
 ## Supported Libraries
 
 The monitor works with any Ruby library that uses Faraday for HTTP(S) requests to LLM APIs, including:
@@ -276,7 +338,7 @@ For standard Ruby scripts or non-Rails applications:
 
 ```ruby
 #!/usr/bin/env ruby
-require 'coolhand'
+require 'coolhand/ruby'
 
 Coolhand.configure do |config|
   config.api_key = 'your_api_key_here'  # Store securely, don't commit to git
@@ -305,6 +367,10 @@ The monitor handles errors gracefully:
 - Invalid API keys will be reported but won't crash your app
 - Network issues are handled with appropriate error messages
 
+## Integration Guides
+
+- **[ElevenLabs Integration](docs/elevenlabs.md)** - Complete guide for integrating ElevenLabs Conversational AI with webhook capture and feedback submission
+
 ## Security
 
 - API keys in request headers are automatically redacted
@@ -324,4 +390,4 @@ The monitor handles errors gracefully:
 
 ## License
 
-Apache-2.0
+Apache-2.0

data/docs/elevenlabs.md

@@ -0,0 +1,408 @@
+# ElevenLabs Integration Guide
+
+This guide explains how to integrate Coolhand with ElevenLabs Conversational AI, including webhook capture and feedback submission from the widget.
+
+## Table of Contents
+- [Overview](#overview)
+- [Webhook Integration](#webhook-integration)
+- [Feedback Collection](#feedback-collection)
+- [Complete Example](#complete-example)
+
+## Overview
+
+ElevenLabs Conversational AI provides voice-based AI assistants. This integration allows you to:
+1. Capture conversation data via webhooks
+2. Fetch and submit user feedback to Coolhand
+3. Track conversation quality and user satisfaction
+
+## Webhook Integration
+
+### Setting Up Webhook Capture
+
+ElevenLabs sends webhooks when conversations occur. Here's how to capture and forward them to Coolhand:
+
+#### 1. Create a Webhook Controller
+
+```ruby
+# app/controllers/webhooks_controller.rb
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def elevenlabs
+    begin
+      # Forward the webhook to Coolhand
+      result = Coolhand.logger_service.forward_webhook(
+        webhook_body: request.raw_post || request.body.read,
+        source: "elevenlabs",
+        event_type: request.headers["X-ElevenLabs-Event"] || "conversation",
+        headers: request.headers
+      )
+
+      if result
+        # Optionally save conversation data locally
+        save_conversation_transcript(params) if params[:type] == "conversation.finished"
+
+        render json: { status: "success" }, status: :ok
+      else
+        render json: { status: "error", message: "Failed to forward webhook" }, status: :unprocessable_entity
+      end
+    rescue => e
+      Rails.logger.error "Webhook processing error: #{e.message}"
+      render json: { status: "error", message: e.message }, status: :internal_server_error
+    end
+  end
+
+  private
+
+  def save_conversation_transcript(webhook_data)
+    ConversationTranscript.create!(
+      conversation_id: webhook_data.dig(:conversation, :conversation_id),
+      transcript: extract_transcript(webhook_data),
+      user_message: extract_user_message(webhook_data),
+      assistant_message: extract_assistant_message(webhook_data),
+      timestamp: Time.current
+    )
+  end
+
+  def extract_transcript(data)
+    transcript = data.dig(:conversation, :transcript) || []
+    transcript.map { |entry| "#{entry[:role]}: #{entry[:message]}" }.join("\n")
+  end
+
+  def extract_user_message(data)
+    transcript = data.dig(:conversation, :transcript) || []
+    user_entries = transcript.select { |entry| entry[:role] == "user" }
+    user_entries.map { |entry| entry[:message] }.join(" ")
+  end
+
+  def extract_assistant_message(data)
+    transcript = data.dig(:conversation, :transcript) || []
+    agent_entries = transcript.select { |entry| entry[:role] == "agent" }
+    agent_entries.map { |entry| entry[:message] }.join(" ")
+  end
+end
+```
+
+#### 2. Configure Routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  post "webhooks/elevenlabs", to: "webhooks#elevenlabs"
+end
+```
+
+#### 3. Configure Coolhand for ElevenLabs
+
+```ruby
+# config/initializers/coolhand.rb
+Coolhand.configure do |config|
+  config.api_key = ENV["COOLHAND_API_KEY"]
+  config.environment = Rails.env
+  config.silent = false
+
+  # Include ElevenLabs API in intercept addresses
+  config.intercept_addresses = [
+    "api.openai.com",
+    "api.anthropic.com",
+    "api.elevenlabs.io"
+  ]
+end
+```
+
+## Feedback Collection
+
+### Fetching Feedback from ElevenLabs API
+
+ElevenLabs stores conversation feedback in the metadata field. Here's how to retrieve and submit it to Coolhand:
+
+#### 1. Create ElevenLabs API Service
+
+```ruby
+# app/services/elevenlabs_api_service.rb
+require 'net/http'
+require 'uri'
+require 'json'
+
+class ElevenlabsApiService
+  BASE_URL = 'https://api.elevenlabs.io'
+  API_KEY = ENV['ELEVENLABS_API_KEY']
+
+  def initialize
+    unless API_KEY
+      raise "ElevenLabs API key is required. Please set ELEVENLABS_API_KEY environment variable."
+    end
+  end
+
+  # Fetch conversation data from ElevenLabs
+  def fetch_conversation(conversation_id)
+    url = "#{BASE_URL}/v1/convai/conversations/#{conversation_id}"
+    uri = URI(url)
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true
+
+    request = Net::HTTP::Get.new(uri)
+    request['xi-api-key'] = API_KEY
+    request['Content-Type'] = 'application/json'
+
+    response = http.request(request)
+
+    if response.code == '200'
+      JSON.parse(response.body)
+    else
+      Rails.logger.error "ElevenLabs API error: #{response.code} - #{response.body}"
+      raise "Failed to fetch conversation: #{response.code}"
+    end
+  rescue => e
+    Rails.logger.error "Error fetching conversation from ElevenLabs: #{e.message}"
+    raise e
+  end
+
+  # Extract feedback data from conversation response
+  def extract_feedback(conversation_data)
+    feedback_data = {}
+
+    # Feedback is located in metadata.feedback
+    if conversation_data.dig('metadata', 'feedback')
+      feedback = conversation_data['metadata']['feedback']
+
+      # Extract rating (numerical score)
+      if feedback['rating']
+        feedback_data[:feedback_rating] = feedback['rating']
+      end
+
+      # Extract comment (text feedback)
+      if feedback['comment'] && !feedback['comment'].empty?
+        feedback_data[:feedback_text] = feedback['comment']
+      end
+    end
+
+    # Return nil if no feedback found
+    return nil if feedback_data.empty?
+
+    feedback_data
+  rescue => e
+    Rails.logger.error "Error extracting feedback: #{e.message}"
+    nil
+  end
+end
+```
+
+#### 2. Create Feedback Controller
+
+```ruby
+# app/controllers/transcripts_controller.rb
+class TranscriptsController < ApplicationController
+  def index
+    @transcripts = ConversationTranscript.order(timestamp: :desc)
+  end
+
+  def fetch_feedback
+    conversation_id = params[:conversation_id]
+
+    begin
+      # Initialize ElevenLabs API service
+      elevenlabs_service = ElevenlabsApiService.new
+
+      # Fetch conversation data from ElevenLabs
+      conversation_data = elevenlabs_service.fetch_conversation(conversation_id)
+
+      # Extract feedback from the response
+      feedback_data = elevenlabs_service.extract_feedback(conversation_data)
+
+      if feedback_data
+        # Submit feedback to Coolhand using llm_provider_unique_id for matching
+        coolhand_feedback = {
+          like: feedback_data[:feedback_rating],
+          explanation: feedback_data[:feedback_text],
+          llm_provider_unique_id: conversation_id # Important: use this field for matching
+        }
+
+        result = Coolhand.feedback_service.create_feedback(coolhand_feedback)
+
+        if result
+          flash[:success] = "Feedback successfully fetched from ElevenLabs and submitted to Coolhand!"
+        else
+          flash[:error] = "Failed to submit feedback to Coolhand"
+        end
+      else
+        flash[:warning] = "No feedback found for this conversation in ElevenLabs"
+      end
+
+    rescue => e
+      flash[:error] = "Error fetching feedback: #{e.message}"
+    end
+
+    redirect_to transcripts_path
+  end
+end
+```
+
+#### 3. Create UI for Feedback Submission
+
+```erb
+<!-- app/views/transcripts/index.html.erb -->
+<div class="container">
+  <h1>Voice Chat Transcripts</h1>
+
+  <% if @transcripts.any? %>
+    <div class="transcripts-list">
+      <% @transcripts.each do |transcript| %>
+        <div class="transcript-item">
+          <div class="transcript-header">
+            <div class="header-info">
+              <strong>Conversation ID:</strong> <%= transcript.conversation_id %>
+              <span class="timestamp"><%= transcript.timestamp&.strftime("%m/%d/%Y %I:%M %p") %></span>
+            </div>
+            <div class="header-actions">
+              <%= form_with url: "/transcripts/fetch_feedback", method: :post, local: true do |form| %>
+                <%= form.hidden_field :conversation_id, value: transcript.conversation_id %>
+                <%= form.submit "Fetch Feedback", class: "btn btn-primary btn-sm" %>
+              <% end %>
+            </div>
+          </div>
+
+          <% if transcript.transcript.present? %>
+            <div class="message full-transcript">
+              <span class="label">Transcript:</span> <%= transcript.transcript %>
+            </div>
+          <% end %>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+</div>
+```
+
+## Complete Example
+
+### Full Rails Integration
+
+Here's a complete example showing how all the pieces work together:
+
+#### 1. Database Migration
+
+```ruby
+# db/migrate/xxx_create_conversation_transcripts.rb
+class CreateConversationTranscripts < ActiveRecord::Migration[7.0]
+  def change
+    create_table :conversation_transcripts do |t|
+      t.string :conversation_id, null: false
+      t.text :transcript
+      t.text :user_message
+      t.text :assistant_message
+      t.datetime :timestamp
+      t.timestamps
+    end
+
+    add_index :conversation_transcripts, :conversation_id, unique: true
+  end
+end
+```
+
+#### 2. Model
+
+```ruby
+# app/models/conversation_transcript.rb
+class ConversationTranscript < ApplicationRecord
+  validates :conversation_id, presence: true, uniqueness: true
+end
+```
+
+#### 3. ElevenLabs Widget Integration
+
+```html
+<!-- app/views/home/index.html.erb -->
+<div id="voice-chat-container">
+  <!-- ElevenLabs Conversational AI Widget -->
+  <elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
+</div>
+
+<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
+```
+
+## Key Points
+
+### Webhook Best Practices
+
+1. **Always forward raw webhook data**: Use `request.raw_post` to preserve the original payload
+2. **Include headers**: ElevenLabs headers contain important metadata
+3. **Set source as "elevenlabs"**: This helps Coolhand properly categorize the data
+4. **Handle errors gracefully**: Log errors but always return 200 OK to prevent webhook retries
+
+### Feedback Matching
+
+1. **Use `llm_provider_unique_id`**: This field allows matching by the ElevenLabs conversation ID
+2. **Don't use `llm_request_log_id`** unless you have the actual Coolhand log ID
+3. **Feedback location**: Look for feedback in `metadata.feedback` in the API response
+
+### Data Structure
+
+ElevenLabs feedback structure in API response:
+```json
+{
+  "metadata": {
+    "feedback": {
+      "type": "rating",
+      "rating": 2,
+      "comment": "didn't work",
+      "likes": 0,
+      "dislikes": 0
+    }
+  }
+}
+```
+
+### Environment Variables
+
+Required environment variables:
+```bash
+COOLHAND_API_KEY=your_coolhand_api_key
+ELEVENLABS_API_KEY=your_elevenlabs_api_key
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Webhook not being received**
+   - Verify your webhook URL is publicly accessible
+   - Check ElevenLabs dashboard for webhook configuration
+   - Look for errors in Rails logs
+
+2. **Feedback not found**
+   - Ensure the user actually provided feedback in the widget
+   - Check that conversation ID is correct
+   - Verify API key has proper permissions
+
+3. **Coolhand submission fails**
+   - Use `llm_provider_unique_id` instead of `llm_request_log_id`
+   - Ensure Coolhand API key is valid
+   - Check that feedback data is properly formatted
+
+### Testing
+
+Test the integration in Rails console:
+```ruby
+# Test ElevenLabs API connection
+service = ElevenlabsApiService.new
+conversation_id = "conv_xxx"
+response = service.fetch_conversation(conversation_id)
+feedback = service.extract_feedback(response)
+
+# Test Coolhand submission
+coolhand_feedback = {
+  like: feedback[:feedback_rating],
+  explanation: feedback[:feedback_text],
+  llm_provider_unique_id: conversation_id
+}
+result = Coolhand.feedback_service.create_feedback(coolhand_feedback)
+```
+
+## Support
+
+For issues specific to:
+- **Coolhand Ruby Gem**: [GitHub Issues](https://github.com/your-org/coolhand-ruby)
+- **ElevenLabs API**: [ElevenLabs Documentation](https://docs.elevenlabs.io)
+- **Integration Questions**: Contact your Coolhand support team

data/lib/coolhand/ruby/api_service.rb

@@ -3,6 +3,7 @@
 require "net/http"
 require "uri"
 require "json"
+require_relative "collector"
 
 module Coolhand
   module Ruby
@@ -29,6 +30,11 @@ module Coolhand
 
       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",
@@ -43,8 +49,18 @@ module Coolhand
 
         request = Net::HTTP::Post.new(uri.request_uri)
         headers = create_request_options(payload)
-        headers.each { |key, value| request[key] = value }
-        request.body = JSON.generate(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)
@@ -54,11 +70,12 @@ module Coolhand
             log success_message
             result
           else
-            puts "❌ Request failed: #{response.code} - #{response.body}"
+            body = response.body.force_encoding("UTF-8") if response.body
+            puts "❌ Request failed: #{response.code} - #{body}"
             nil
           end
         rescue StandardError => e
-          puts "❌ Request error: #{e.message}"
+          log "❌ Request error: #{e.message}"
           nil
         end
       end
@@ -71,9 +88,11 @@ module Coolhand
         log("═" * 60) unless silent
       end
 
-      def create_feedback(feedback)
+      def create_feedback(feedback, collection_method = nil)
+        feedback_with_collector = add_collector_to_data(feedback, collection_method)
+
         payload = {
-          llm_request_log_feedback: feedback
+          llm_request_log_feedback: feedback_with_collector
         }
 
         log_feedback_info(feedback)
@@ -87,11 +106,11 @@ module Coolhand
         result
       end
 
-      def create_log(captured_data)
+      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: captured_data
-          }
+          llm_request_log: raw_request_with_collector
         }
 
         log_request_info(captured_data)
@@ -107,12 +126,68 @@ module Coolhand
         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
 
-        puts "\n📝 CREATING FEEDBACK for LLM Request Log ID: #{feedback[:llm_request_log_id]}"
+        # 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]

data/lib/coolhand/ruby/collector.rb

@@ -0,0 +1,21 @@
+# 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

@@ -11,7 +11,7 @@ module Coolhand
       @environment = "production"
       @api_key = nil
       @silent = false
-      @intercept_addresses = ["api.openai.com", "api.anthropic.com"]
+      @intercept_addresses = ["api.openai.com", "api.anthropic.com", "api.elevenlabs.io", ":generateContent"]
     end
 
     # Custom setter that preserves defaults when nil/empty array is provided

data/lib/coolhand/ruby/feedback_service.rb

@@ -9,7 +9,9 @@ module Coolhand
         super("v2/llm_request_log_feedbacks")
       end
 
-      public :create_feedback
+      def create_feedback(feedback)
+        super(feedback, "manual")
+      end
     end
   end
 end

data/lib/coolhand/ruby/logger_service.rb

@@ -10,7 +10,104 @@ module Coolhand
       end
 
       def log_to_api(captured_data)
-        create_log(captured_data)
+        create_log(captured_data, "auto-monitor")
+      end
+
+      # Helper method for forwarding webhook data to Coolhand
+      def forward_webhook(webhook_body:, source:, event_type: nil, headers: {}, **options)
+        # Validate required parameters
+        unless Coolhand.required_field?(webhook_body)
+          error_msg = "webhook_body is required and cannot be nil or empty"
+          if Coolhand.configuration.silent
+            puts "COOLHAND WARNING: #{error_msg}"
+            return false
+          else
+            raise ArgumentError, error_msg
+          end
+        end
+
+        unless Coolhand.required_field?(source)
+          error_msg = "source is required and cannot be nil or empty"
+          if Coolhand.configuration.silent
+            puts "COOLHAND WARNING: #{error_msg}"
+            return false
+          else
+            raise ArgumentError, error_msg
+          end
+        end
+
+        # Auto-generate required fields unless provided
+        webhook_data = {
+          id: options[:id] || SecureRandom.uuid,
+          timestamp: options[:timestamp] || Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ"),
+          method: options[:method] || "POST",
+          url: options[:url] || build_webhook_url(source, event_type),
+          headers: sanitize_headers(headers),
+          request_body: clean_webhook_body(webhook_body, source),
+          response_body: options[:response_body],
+          response_headers: options[:response_headers],
+          status_code: options[:status_code] || 200,
+          source: "#{source}_webhook"
+        }.merge(options.slice(:metadata, :conversation_id, :agent_id))
+
+        # Send to API asynchronously
+        log_to_api(webhook_data)
+      end
+
+      private
+
+      def build_webhook_url(source, event_type)
+        base = "webhook://#{source}"
+        event_type ? "#{base}/#{event_type}" : base
+      end
+
+      def sanitize_headers(headers)
+        return {} if headers.nil?
+        return {} if headers.respond_to?(:empty?) && headers.empty?
+        return {} unless headers.respond_to?(:each)
+
+        # Handle Rails request headers or plain hash
+        clean_headers = {}
+        headers.each do |key, value|
+          next unless key && value
+
+          # Convert Rails HTTP_ prefix headers
+          clean_key = key.to_s.gsub(/^HTTP_/, "").tr("_", "-").downcase
+
+          # Redact sensitive headers
+          clean_value = clean_key.match?(/key|token|secret|authorization|signature/i) ? "[REDACTED]" : value.to_s
+          clean_headers[clean_key] = clean_value
+        end
+        clean_headers
+      end
+
+      def clean_webhook_body(body, source)
+        # Service-specific binary field filters
+        binary_fields = case source.to_s.downcase
+                        when "elevenlabs"
+                          %w[full_audio audio audio_data raw_audio audio_base64 voice_sample audio_url]
+                        when "twilio"
+                          %w[recording_url media_url]
+                        else
+                          %w[audio_data image_data file_content binary_content]
+        end
+
+        remove_binary_fields(body, binary_fields)
+      end
+
+      def remove_binary_fields(obj, fields_to_remove)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), cleaned|
+            next if fields_to_remove.any? { |field| key.to_s.downcase.include?(field) }
+
+            cleaned[key] = remove_binary_fields(value, fields_to_remove)
+          end
+        when Array
+          obj.map { |item| remove_binary_fields(item, fields_to_remove) }
+        else
+          obj
+        end
       end
     end
   end

data/lib/coolhand/ruby/version.rb

@@ -2,6 +2,6 @@
 
 module Coolhand
   module Ruby
-    VERSION = "0.1.2"
+    VERSION = "0.1.4"
   end
 end

data/lib/coolhand/ruby.rb

@@ -7,6 +7,7 @@ require "securerandom"
 
 require_relative "ruby/version"
 require_relative "ruby/configuration"
+require_relative "ruby/collector"
 require_relative "ruby/interceptor"
 require_relative "ruby/api_service"
 require_relative "ruby/logger_service"
@@ -77,5 +78,13 @@ module Coolhand
     def logger_service
       Ruby::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

data/lib/coolhand.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Main entry point for the Coolhand gem
+require_relative "coolhand/ruby"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-22 00:00:00.000000000 Z
+date: 2025-12-06 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.
@@ -28,8 +28,11 @@ files:
 - README.md
 - Rakefile
 - coolhand-ruby.gemspec
+- 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