coolhand 0.1.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04f5762e1c9b3dad57c3b65fbe6860a0394fd793f49e67538eaf8c68584ccae5
-  data.tar.gz: d666c068c33af71f895228030d6342008ccdae290de4c603dec687cf07b5645d
+  metadata.gz: 6a7e878a6cb441cee3e29de825ba5b0d5b01285475f42d5a4f66386f37379098
+  data.tar.gz: fcc866bd1ca6e7348fbd3ff2daf75ba9203981c09acfaa6062873a08e11b5370
 SHA512:
-  metadata.gz: 4a9de9973617ef1a0816811a5d29dc43ebdda8eb11540474d15e350670a675f4826ff6d9eac56aad5e82dbebdeb50a812ab8bc96d8a16a9f522d27294e6f8035
-  data.tar.gz: 382033854564a57ced160afad00bec423d551a2aaeda70a69cfc9a1a2eaf83843dfe6c3479ca3733ff71a436516032a06c0d1b7dc7f8bc937bd49e5376f51049
+  metadata.gz: 7b7f36ff49b826fb34691488c3839de760c7f01c58f811e1bb9108b896da71d958f2e1a714486513da0c1a264278078784ee4065be165b72b349939128e4a9e8
+  data.tar.gz: c3bcb5e2a7d3bb07e8e66483bb5c64d3a27b4ad7b7cd677a7bc7aa74b8d612ad53b3b373f21244d3fdf14fb32a34ccee1f80e227b740d3634b7fb6074b7ee64a

data/.rubocop.yml

@@ -1,7 +1,8 @@
 # This is the configuration used to check the rubocop source code.
 
-require:
+plugins:
   - rubocop-performance
+require:
   - rubocop-rspec
 inherit_gem:
   test-prof: config/rubocop-rspec.yml
@@ -124,6 +125,12 @@ Layout/EndAlignment:
 Naming/VariableNumber:
   Enabled: false
 
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
 # Lint rules
 Lint/EmptyClass:
   Enabled: false
@@ -138,6 +145,12 @@ RSpec/HookArgument:
 RSpec/MultipleExpectations:
   Enabled: false
 
+RSpec/VerifiedDoubleReference:
+  Enabled: false
+
+RSpec/MessageChain:
+  Enabled: false
+
 RSpec/ExampleLength:
   Enabled: false
 

data/CHANGELOG.md

@@ -5,6 +5,104 @@ 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.3.0] - 2026-05-14
+
+### 🚀 Major Changes
+- **Unified Net::HTTP Interceptor** - Replaced dual interceptor architecture (Faraday + Anthropic) with a single `NetHttpInterceptor` that captures all HTTP traffic via `Module#prepend`
+- **Simplified Namespace** - Removed `Coolhand::Ruby` namespace; all classes now under `Coolhand` directly (e.g., `Coolhand::FeedbackService` instead of `Coolhand::Ruby::FeedbackService`)
+- **Ruby 4.0 Compatibility** - Full support for Ruby 4.0 with conditional debugger dependencies
+- **Google Gemini API Support** - `generativelanguage.googleapis.com` and `:streamGenerateContent` added to default `intercept_addresses`; both `generateContent` and `streamGenerateContent` endpoints are intercepted out of the box
+- **Anthropic API Support Restored** - `api.anthropic.com` added to default `intercept_addresses`; accidentally dropped during the v0.3.0 refactor that replaced `AnthropicInterceptor` with the unified `NetHttpInterceptor`
+- **URL Query Parameter Sanitization** - New `sanitize_url` helper redacts sensitive query parameters (`key`, `api_key`, `apikey`, `token`, `access_token`, `secret`) before logging; protects API keys passed as URL params (common with Gemini's `?key=` pattern)
+
+### ✨ New Features
+- **GitHub Models API** - `models.github.ai` (current endpoint) and `models.inference.ai.azure.com` (deprecated endpoint) added to default `intercept_addresses`; calls routed through GitHub Copilot credentials are now captured automatically without manual configuration. Default intercept addresses are loaded from `default_intercept_addresses.yml` to make future additions a single-line YAML change.
+- **`config.base_url`** - Configurable API destination for self-hosted deployments. Defaults to `https://coolhandlabs.com/api`; set to any `https://` URL to redirect logs and feedback POSTs to your own backend. `http://localhost` and `http://127.0.0.1` are also accepted for local development. Trailing slashes are normalized automatically.
+- **Feedback `sentiment` field** - New string field for feedback: `'like'`, `'dislike'`, or `'neutral'`. Preferred over the boolean `like` field for richer signal.
+- **Feedback `workload_hashid` field** - New string field to associate feedback with a specific workload.
+- **Batch Processing Support** - New `Coolhand::OpenAi::BatchResultProcessor` and `Coolhand::Vertex::BatchResultProcessor` for logging completed async batch jobs as individual `llm_request_log` entries
+- **OpenAI Webhook Validation** - New `Coolhand::OpenAi::WebhookValidator` verifies webhook signatures using HMAC-SHA256 with timing-safe comparison; lenient in development, strict in production/staging
+- **WebhookInterceptor Rails Module** - `Coolhand::WebhookInterceptor` mixin for Rails controllers to validate and dispatch OpenAI batch completion webhooks automatically
+- **Capture Control** - New `config.capture` global toggle (default: `true`) and `config.debug_mode` (captures locally, skips API forwarding) for fine-grained interception control
+- **Thread-Safe Block Control** - `Coolhand.with_capture { }` and `Coolhand.without_capture { }` for scoped override of capture behavior within a block; uses thread-local storage
+- **Exclude API Patterns** - New `config.exclude_api_patterns` deny-list checked after the `intercept_addresses` allow-list; default excludes `["/batchPredictionJobs/"]` to suppress Vertex AI batch job management noise
+
+### 🚫 Deprecated
+- **Feedback `like` field** - The boolean `like` field is deprecated. Use `sentiment: 'like'` or `sentiment: 'dislike'` instead.
+
+### 🏗️ Architecture Improvements
+- **Single Interceptor** - `NetHttpInterceptor` patches `Net::HTTP#request` and `Net::HTTPResponse#read_body`; removed ~1,400 lines of interceptor-specific code
+- **Thread-Safe Streaming** - Uses `Thread.current[:coolhand_stream_buffer]` for streaming response capture
+- **Capture Priority Hierarchy** - `debug_mode` (always capture) > thread-local override > global `capture` config
+
+### 🐛 Bug Fixes
+- **Streaming Response Encoding** - Streamed response content is now force-encoded to UTF-8 before JSON parsing, eliminating noisy `BINARY` encoding warnings for multi-byte responses.
+- **Double-Capture with `Net::HTTP.new` Pattern** - Fixed double-logging when callers use `Net::HTTP.new(host, port).request(req)` without an explicit `start` block. The re-entry guard is now per-connection-object (using a `compare_by_identity` Hash) rather than a boolean thread-local, so independent requests on a different `Net::HTTP` instance inside a callback are still captured.
+- **Provider-Neutral Readiness Log** - Startup console message no longer names a single provider; it now reflects all monitored inference URIs.
+- **Interceptor No Longer Silently Drops Logs on HTTP Errors** - Wrapped `Net::HTTP#request` in `begin/rescue/ensure` so `send_complete_request_log` is always called even when the SDK raises an exception (e.g., `Anthropic::Errors::NotFoundError` on a 404). Status is extracted from the exception via `.status`, `.response.status`, or message parsing.
+
+### 📦 Dependencies
+- Bumped `faraday` from 2.14.0 to 2.14.1
+
+### 💔 Breaking Changes
+- **`config.base_url` validation** - `Coolhand.configure` now raises `Coolhand::Error` if `base_url` is set to a plain `http://` URL (non-localhost). Previously any string was accepted silently. If you were pointing at an internal `http://` host (e.g. `http://logs.internal/api`), you will need to either enable TLS on that host or use an `https://` proxy in front of it.
+- **Namespace Change** - `Coolhand::Ruby::*` references must be updated to `Coolhand::*`
+- **Removed Files** - `faraday_interceptor.rb` and `anthropic_interceptor.rb` replaced by `net_http_interceptor.rb`
+- **`environment` Config Behavior** - The `environment` attribute no longer controls whether requests are forwarded to the API. Use `config.debug_mode = true` instead if you previously relied on `environment: "development"` to suppress API calls.
+
+### 🔄 Migration Guide
+1. Update gem dependency to `~> 0.3.0`
+2. Replace `Coolhand::Ruby::` with `Coolhand::` in all class references
+3. If using `environment: "development"` to prevent API calls, switch to `config.debug_mode = true`
+4. If `config.base_url` was set to a plain `http://` (non-localhost) URL, switch to `https://` or use an `https://` proxy
+5. No other changes needed to `Coolhand.configure` blocks for basic usage
+
+## [0.2.0] - 2025-12-16
+
+### ✨ Major New Features
+- **Official Anthropic Gem Support** - Added comprehensive monitoring support for the official `anthropic` gem (v1.8+) through direct Net::HTTP interception
+- **Dual Gem Compatibility** - Support for both `anthropic` (official) and `ruby-anthropic` (community) gems with automatic detection and appropriate interceptor selection
+- **Streaming Response Support** - Enhanced SSE (Server-Sent Events) parsing for Anthropic streaming responses with proper message accumulation and reconstruction
+- **Graceful Gem Conflict Handling** - Automatic detection when both anthropic gems are installed, with graceful degradation to ruby-anthropic monitoring
+
+### 🏗️ Architecture Improvements
+- **AnthropicInterceptor Module** - New dedicated interceptor for official anthropic gem requests with streaming response support
+- **BaseInterceptor Module** - Shared functionality across interceptors with unified API logging format and DRY principles
+- **Modular Design** - Moved from single `interceptor.rb` to specialized interceptors (`faraday_interceptor.rb`, `anthropic_interceptor.rb`)
+- **Enhanced Configuration** - Automatic gem detection in `configure` block with appropriate interceptor selection
+
+### 🔧 API & Format Changes
+- **Unified Logging Format** - Standardized API request/response logging with `raw_request` wrapper and collector data integration
+- **Headers Field Update** - API logs now use `headers` instead of `request_headers` for consistency
+- **Silent Mode Override** - Critical warnings (like gem conflicts) now always display regardless of silent mode settings
+
+### 🧪 Testing & Quality
+- **Comprehensive Test Coverage** - Added 16 new specs covering all interceptor scenarios including gem conflict handling
+- **RuboCop Compliance** - Applied linting with proper line length, verified doubles, and RSpec best practices
+- **Thread Safety** - Enhanced request correlation with thread-local storage for streaming requests
+
+### 🗂️ Supported Environments
+- **Development Environment** - Uses official `anthropic` gem for Net::HTTP-based requests
+- **AR_Dev Environment** - Uses `ruby-anthropic` gem for Faraday-based requests
+- **Automatic Detection** - Coolhand detects which gem is loaded and applies appropriate interception
+
+### 💔 Breaking Changes
+- **Removed** - `lib/coolhand/ruby/interceptor.rb` replaced by specialized interceptor modules
+- **API Change** - Logging format now uses `headers` field instead of `request_headers`
+
+### 🔄 Migration Guide
+For users upgrading from v0.1.x:
+- No code changes required for basic usage
+- If depending on old `interceptor.rb` directly, update imports to use `faraday_interceptor.rb` or `anthropic_interceptor.rb`
+- API log consumers should expect `headers` field instead of `request_headers`
+
+### 📊 Compatibility Matrix
+| Gem | Version | Interceptor | Status |
+|-----|---------|-------------|--------|
+| `anthropic` | 1.8+ | AnthropicInterceptor | ✅ Full Support |
+| `ruby-anthropic` | 0.4+ | FaradayInterceptor | ✅ Full Support |
+| Both gems | Any | FaradayInterceptor | ⚠️ Graceful Degradation |
+
 ## [0.1.5] - 2024-12-09
 
 ### 🐛 Critical Bug Fixes
@@ -19,7 +117,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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
+- **Added Collector Module** - New `Coolhand::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
 

data/CLAUDE.md

@@ -0,0 +1,34 @@
+# Development Guidelines
+
+## Optional Provider Dependencies
+
+Coolhand supports multiple LLM providers (OpenAI, Anthropic, Google Gemini, etc.). These provider gems should **never** be required at gem load time, as clients may not use all providers and shouldn't be forced to install unnecessary dependencies.
+
+**Rule**: Any require for provider SDKs (openai, anthropic, google-generativeai, etc.) must be:
+1. Placed in the file where it's actually used (not in the main coolhand.rb)
+2. Only executed when that provider's functionality is accessed
+3. Not declared as a hard dependency in coolhand-ruby.gemspec
+
+Example pattern:
+```ruby
+# ❌ DON'T: In lib/coolhand.rb (loads unconditionally)
+require "openai"
+
+# ✅ DO: In lib/coolhand/open_ai/batch_result_processor.rb (only when needed)
+require "openai"
+
+module Coolhand
+  module OpenAi
+    class BatchResultProcessor
+      def client
+        @client ||= OpenAI::Client.new
+      end
+    end
+  end
+end
+```
+
+This ensures:
+- Gem loads cleanly regardless of what providers are installed
+- Apps using path gems (local development) don't break from missing optional dependencies
+- Users only need gems for providers they actually use

data/README.md

@@ -24,7 +24,7 @@ gem 'coolhand'
 
 ```ruby
 # Add this configuration at the start of your application
-require 'coolhand/ruby'
+require 'coolhand'
 
 Coolhand.configure do |config|
   config.api_key = 'your_api_key_here'
@@ -47,15 +47,38 @@ end
 - ⚡ **Performance optimized** - Negligible overhead via async logging
 - 🛡️ **Future-proof** - Automatically captures new AI calls added by your team
 
+## Self-Hosted Deployments
+
+For compliance, data-residency, or cost reasons you can run your own Coolhand-compatible endpoint and point the SDK at it via `config.base_url`:
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key  = ENV['COOLHAND_API_KEY']
+  config.base_url = ENV['COOLHAND_BASE_URL']  # e.g. "https://coolhand.internal.example.com/api"
+end
+```
+
+When `base_url` is unset the SDK defaults to `https://coolhandlabs.com/api` and behaviour is unchanged.
+
+**Accepted values:**
+- Any `https://` URL — required for production use
+- `http://localhost` or `http://127.0.0.1` — accepted for local development only
+
+**Trailing slashes** are stripped automatically, so `"https://example.com/api/"` and `"https://example.com/api"` are equivalent.
+
+The SDK raises `Coolhand::Error` at configure time if `base_url` is set to a plain `http://` URL pointing at a non-localhost host.
+
 ## Feedback API
 
-Collect feedback on LLM responses to improve model performance:
+Collect feedback on LLM responses to improve model performance.
+
+> **Frontend Feedback Widget**: For browser-based feedback collection, see [coolhand-js](https://github.com/Coolhand-Labs/coolhand-js) - an accessible, lightweight JavaScript widget that leverages best UX practices to capture actionable user feedback on any AI output.
 
 ```ruby
-require 'coolhand/ruby'
+require 'coolhand'
 
 # Create feedback for an LLM response
-feedback_service = Coolhand::Ruby::FeedbackService.new(Coolhand.configuration)
+feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
 
 feedback = feedback_service.create_feedback(
   llm_request_log_id: 123,
@@ -65,7 +88,7 @@ feedback = feedback_service.create_feedback(
   original_output: 'Here is the original LLM response!',
   revised_output: 'Here is the human edit of the original LLM response.',
   explanation: 'Tone of the original response read like AI-generated open source README docs',
-  like: true
+  sentiment: 'dislike'
 )
 ```
 
@@ -80,7 +103,9 @@ feedback = feedback_service.create_feedback(
 ### Quality Data
 - **`revised_output`** ⭐ *Best Signal* - End user revision of the LLM response. The highest value data for improving quality scores.
 - **`explanation`** 💬 *Medium Signal* - End user explanation of why the response was good or bad. Valuable qualitative data.
-- **`like`** 👍 *Low Signal* - Boolean like/dislike. Lower quality signal but easy for users to provide.
+- **`sentiment`** 🎭 *Preferred* - String sentiment: `'like'`, `'dislike'`, or `'neutral'`. Takes precedence over `like` if both are provided. The gem automatically converts `like` to `sentiment` before sending.
+- **`like`** 👍 *Low Signal (Deprecated)* - Boolean: `true` = like, `false` = dislike. Use `sentiment` instead. Conversion: `true` → `"like"`, `false` → `"dislike"`.
+- **`workload_hashid`** 🔗 *Workload Association* - Hashid of a workload to associate this feedback with.
 - **`creator_unique_id`** 👤 *User Tracking* - Unique ID to match feedback to the end user who created it
 
 ## Rails Integration
@@ -100,7 +125,7 @@ Coolhand.configure do |config|
   config.silent = Rails.env.production?
 
   # Specify which LLM endpoints to intercept (array of strings)
-  # Optional - defaults to ["api.openai.com", "api.anthropic.com"]
+  # Optional - defaults to OpenAI, Anthropic, ElevenLabs, Google Gemini, and GitHub Models
   # config.intercept_addresses = ["api.openai.com", "api.anthropic.com", "api.cohere.ai"]
 end
 ```
@@ -110,7 +135,7 @@ end
 ```ruby
 class ChatController < ApplicationController
   def create_feedback
-    feedback_service = Coolhand::Ruby::FeedbackService.new(Coolhand.configuration)
+    feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
 
     feedback = feedback_service.create_feedback(
       llm_request_log_id: params[:log_id],
@@ -118,7 +143,7 @@ class ChatController < ApplicationController
       original_output: params[:original_response],
       revised_output: params[:edited_response],
       explanation: params[:feedback_text],
-      like: params[:thumbs_up]
+      sentiment: params[:sentiment]
     )
 
     if feedback
@@ -135,14 +160,14 @@ end
 ```ruby
 class FeedbackCollectionJob < ApplicationJob
   def perform(feedback_data)
-    feedback_service = Coolhand::Ruby::FeedbackService.new(Coolhand.configuration)
+    feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
 
     feedback_service.create_feedback(
       llm_provider_unique_id: feedback_data[:request_id],
       creator_unique_id: feedback_data[:user_id],
       original_output: feedback_data[:original],
       explanation: feedback_data[:reason],
-      like: feedback_data[:positive]
+      sentiment: feedback_data[:sentiment]
     )
   end
 end
@@ -164,7 +189,7 @@ end
 
 ```ruby
 require 'openai'
-require 'coolhand/ruby'
+require 'coolhand'
 
 # Configure Coolhand
 Coolhand.configure do |config|
@@ -186,29 +211,7 @@ puts response.dig("choices", 0, "message", "content")
 # The request and response have been automatically logged to Coolhand!
 ```
 
-### With Anthropic Ruby Client
-
-```ruby
-require 'anthropic'
-require 'coolhand/ruby'
-
-# Configure Coolhand
-Coolhand.configure do |config|
-  config.api_key = 'your_api_key_here'
-end
-
-# Use Anthropic normally - requests are automatically logged
-anthropic = Anthropic::Client.new(access_token: ENV['ANTHROPIC_API_KEY'])
-
-response = anthropic.messages(
-  model: "claude-3-opus",
-  max_tokens: 1024,
-  messages: [{ role: "user", content: "Hello, Claude!" }]
-)
-
-puts response["content"]
-# Automatically logged to Coolhand!
-```
+📖 **[Complete Anthropic Integration Guide →](docs/anthropic.md)** - Supports both official and community gems with automatic detection
 
 ## Logging Inbound Webhooks
 
@@ -285,23 +288,41 @@ The filtering is automatic and applies to all monitored API calls and webhook lo
 
 ## Supported Libraries
 
-The monitor works with any Ruby library that uses Faraday for HTTP(S) requests to LLM APIs, including:
+The monitor works with multiple transport layers and Ruby libraries:
 
+**Faraday-based libraries:**
 - OpenAI Ruby SDK
-- Anthropic Ruby SDK
+- ruby-anthropic gem (community Anthropic gem)
 - ruby-openai gem
 - LangChain.rb
 - Direct Faraday requests
 - Any other Faraday-based HTTP client
 
+**Native HTTP libraries:**
+- Official Anthropic Ruby SDK (using Net::HTTP)
+- GitHub Models SDK / any client using `models.github.ai`
+- Any library using Net::HTTP directly
+
+**Universal Coverage**: Since most Ruby HTTP libraries use Net::HTTP under the hood, Coolhand's single interceptor provides comprehensive monitoring without needing library-specific integrations.
+
 ## How It Works
 
-The gem patches Faraday connections to intercept HTTP requests. When a request matches the configured LLM endpoints:
+Coolhand uses a unified Net::HTTP interceptor to monitor all HTTP traffic to configured LLM endpoints:
+
+### Net::HTTP Interceptor
+- Patches Ruby's core `Net::HTTP` library using `Module#prepend`
+- Monitors **all** HTTP libraries that use Net::HTTP under the hood (which is most of them)
+- Handles both standard requests and streaming responses via `read_body` interception
+- Thread-safe design using thread-local storage for streaming buffers
 
-1. The original request executes normally
-2. Request and response data (body, headers, status) are captured
-3. Data is sent to the Coolhand API asynchronously in a background thread
-4. Your application continues without any performance impact
+### Request Flow
+When a request matches configured LLM endpoints:
+
+1. The original request executes normally with zero performance impact
+2. Request and response data (body, headers, status) are captured by the interceptor
+3. For streaming requests, the complete accumulated response is captured (not individual chunks)
+4. Data is sent to the Coolhand API asynchronously in a background thread
+5. Your application continues without interruption
 
 For non-matching endpoints, requests pass through unchanged.
 
@@ -338,7 +359,7 @@ For standard Ruby scripts or non-Rails applications:
 
 ```ruby
 #!/usr/bin/env ruby
-require 'coolhand/ruby'
+require 'coolhand'
 
 Coolhand.configure do |config|
   config.api_key = 'your_api_key_here'  # Store securely, don't commit to git
@@ -367,8 +388,105 @@ 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
 
+
+## Batch webhook handler (OpenAI)
+
+Automatically handle OpenAI batch event logs (batch.completed, batch.failed, batch.expired, batch.cancelled)
+by intercepting webhook requests and enqueuing your batch result processor.
+
+Usage:
+- Include the interceptor in your controller:
+  include Coolhand::WebhookInterceptor
+- Add the before_action to validate and populate @validator payload:
+  before_action :intercept_batch_request, only: :openai
+- Ensure you skip CSRF for the webhook endpoint:
+  skip_before_action :verify_authenticity_token
+- Override the webhook_secret method to return your OpenAI webhook secret
+
+Minimal example (only key lines shown):
+
+```ruby
+# app/controllers/webhooks/batch_api_requests_controller.rb
+# ...existing code...
+include Coolhand::WebhookInterceptor
+
+skip_before_action :verify_authenticity_token
+before_action :intercept_batch_request, only: :openai
+
+def openai
+  event = JSON.parse(@validator.payload)
+  case event["type"]
+  when "batch.completed", "batch.failed", "batch.expired", "batch.cancelled"
+    batch_id = event.dig("data", "id")
+    batch_request = BatchApiRequest.find_by(provider: "openai", provider_batch_id: batch_id)
+
+    if batch_request
+      OpenAi::BatchResultProcessor.perform_async(batch_request.id)
+      Rails.logger.info("Queued batch result processing for BatchApiRequest #{batch_request.id}")
+    else
+      Rails.logger.warn("Could not find BatchApiRequest for OpenAI batch ID: #{batch_id}")
+    end
+  else
+    Rails.logger.info("Unhandled OpenAI webhook event type: #{event["type"]}")
+  end
+
+  head :ok
+rescue JSON::ParserError
+  head :bad_request
+rescue StandardError => e
+  Rails.logger.error("OpenAI webhook error: #{e.message}")
+  head :internal_server_error
+end
+
+def webhook_secret
+  Rails.application.credentials.openai_webhook_secret
+end
+# ...existing code...
+```
+
+## Batch webhook handler (Vertex)
+
+Automatically handle Vertex batch event logs.
+
+Usage:
+- call Coolhand::Vertex::BatchResultProcessor service with batch_info and download batch results
+
+Minimal example (only key lines shown):
+
+```ruby
+class Vertex::BatchCallbackProcessor < BaseService
+  option :batch_request, model: BatchApiRequest
+  option :batch_info
+
+  def call
+    case batch_info["state"]
+    when "JOB_STATE_PENDING"
+      nil
+    when "JOB_STATE_RUNNING", "JOB_STATE_QUEUED"
+      batch_request.update!(status: "processing")
+
+      Coolhand::Vertex::BatchResultProcessor.new(batch_info:).call
+    when "JOB_STATE_SUCCEEDED"
+      output_file_id = batch_info["outputInfo"]["gcsOutputDirectory"]
+      results = download_batch_results(output_file_id)
+      results.each { |batch_item| process_batch_result(batch_item) }
+
+      batch_request.update!(status: "completed", completed_at: Time.current, output_file_id:)
+
+      Coolhand::Vertex::BatchResultProcessor.new(batch_info:).call(results)
+
+      # Clean up GCS files after successful processing
+      cleanup_gcs_files(output_file_id)
+    when "JOB_STATE_FAILED"
+      handle_failed_batch(batch_info["error"]["message"])
+    end
+  end
+end
+```
+
 ## Integration Guides
 
+- **[Anthropic Integration](docs/anthropic.md)** - Complete guide for both official and community Anthropic gems, including streaming, dual gem handling, and troubleshooting
 - **[ElevenLabs Integration](docs/elevenlabs.md)** - Complete guide for integrating ElevenLabs Conversational AI with webhook capture and feedback submission
 
 ## Security
@@ -377,10 +495,11 @@ The monitor handles errors gracefully:
 - No sensitive data is exposed in logs
 - All data is sent via HTTPS to Coolhand servers
 
-## Other Languages
+## Related Packages
 
-- **Node.js**: [coolhand-node package](https://github.com/coolhand-io/coolhand-node) - Coolhand monitoring for Node.js applications
-- **API Docs**: [API Documentation](https://coolhandlabs.com/docs) - Direct API integration documentation
+- **Frontend (Feedback Collection Widget)**: [coolhand-js](https://github.com/Coolhand-Labs/coolhand-js) - Frontend feedback widget for collecting user feedback on AI outputs
+- **Node.js**: [coolhand-node package](https://github.com/Coolhand-Labs/coolhand-node) - Coolhand monitoring for Node.js applications
+- **Python**: [coolhand package](https://github.com/Coolhand-Labs/coolhand-python) - Coolhand monitoring for Python applications
 
 ## Community
 

data/coolhand-ruby.gemspec

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
-require_relative "lib/coolhand/ruby/version"
+require_relative "lib/coolhand/version"
 
 Gem::Specification.new do |spec|
   spec.name = "coolhand"
-  spec.version = Coolhand::Ruby::VERSION
+  spec.version = Coolhand::VERSION
   spec.authors = ["Michael Carroll", "Yaroslav Malyk"]
   spec.email = ["mc@coolhandlabs.com"]
 
-  spec.summary = "Intercepts and logs OpenAI API calls from a Ruby application."
-  spec.description = "A Ruby gem to automatically monitor and log external LLM requests. It patches Net::HTTP " \
-                     "to capture request and response data."
+  spec.summary = "Monitor and log LLM API calls from OpenAI, Anthropic, and other providers to Coolhand analytics."
+  spec.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."
   spec.homepage = "https://coolhandlabs.com/"
   spec.license = "Apache-2.0"
   spec.required_ruby_version = ">= 3.0.0"
@@ -19,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/Coolhand-Labs/coolhand-ruby"
-  spec.metadata["changelog_uri"] = "https://github.com/Coolhand-Labs/coolhand-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/Coolhand-Labs/coolhand-ruby/blob/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -36,6 +38,8 @@ Gem::Specification.new do |spec|
   # Uncomment to register a new dependency of your gem
   # spec.add_dependency "example-gem", "~> 1.0"
 
+  spec.add_dependency "base64", "~> 0.2"
+
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html
   spec.metadata["rubygems_mfa_required"] = "true"