coolhand 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc0fc356a6cf69d4a0c67a906000cab9590d9fc2a452efec8037a7f541efa561
-  data.tar.gz: ec6f7a136ae1d8e139bf638175b81a2dda063b9bf19d0199ab7f7135cf6d833d
+  metadata.gz: 3f66ea8b94e39769d66543c75987c2108397f89c93dc53748753b396ca76d921
+  data.tar.gz: 560b9ec89c71b31095b5f579bb270b295a79b87a7edbec495179f6f1b764f77e
 SHA512:
-  metadata.gz: 131465dcaf94ae8cc4b5dce47252fe92effc9693ba4de6e61247714c682a717934fa3144cf3228bf754fe89a53803051f32a895c3a42fd3c07990d4cf74286a5
-  data.tar.gz: 26e03d0f27b9acbeb36ff6a0e0ee11cca55b8142cd17d494972013534ba4d8b3753b29fb3565dedb8c0f8daf1e26d7af443353999f5956f5b1b7b8d7ea139585
+  metadata.gz: ebd806bb3744d3fd16673a98f7746b144b468a158ec855b32a4ba142cf110ff4a78b03ea1b95106b8f29d011425bbe0ec44b8f853acb87b9e4037cf87843991f
+  data.tar.gz: 3a8078f5dbe7f3a5c7a0892b391a7085d54b5a6aa1db386075e34470c89802ca0bd6bb5dc5654dffa7fcb2595da3df7b2210a52568595c5c77929e435d1a13b8

data/.rubocop.yml

@@ -125,6 +125,12 @@ Layout/EndAlignment:
 Naming/VariableNumber:
   Enabled: false
 
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
 # Lint rules
 Lint/EmptyClass:
   Enabled: false
@@ -139,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,73 @@ 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).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-06-22
+
+### Added
+- **More default intercept addresses** — Vertex AI (`aiplatform.googleapis.com`), Cloudflare AI Gateway (`gateway.ai.cloudflare.com`), AWS Bedrock OpenAI-compatible endpoint (`bedrock-runtime`), and OpenRouter (`openrouter.ai`) are now monitored out of the box with no configuration required (#66).
+- **`Configuration#enabled` flag** — Set `config.enabled = false` (e.g. `config.enabled = Rails.env.production?`) to skip all patching and validation globally without restructuring your configure block (#68).
+- **Feedback `creator_type` field** — Pass `creator_type: 'human'`, `'agent'`, or `'unknown'` when submitting feedback to identify who originated the feedback; matches the Coolhand API field (#67).
+
+### Changed
+- **Deferred `api_key` validation** — A missing `api_key` no longer raises at `Coolhand.configure` time. Intercepted requests are silently skipped (with a warning log) when the key is absent, so apps that boot without a key in CI or non-production environments no longer crash (#68).
+
+### Dependencies
+- Bumped `faraday` from 2.14.1 to 2.14.2 (#63).
+
+## [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
@@ -65,7 +132,7 @@ For users upgrading from v0.1.x:
 - **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

@@ -1,5 +1,7 @@
 # Coolhand Ruby Monitor
 
+[![Gem Version](https://badge.fury.io/rb/coolhand.svg)](https://badge.fury.io/rb/coolhand)
+
 Monitor and log LLM API calls from multiple providers (OpenAI, Anthropic, Google AI, Cohere, and more) to the Coolhand analytics platform.
 
 ## Installation
@@ -24,7 +26,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 +49,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 +90,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,8 +105,11 @@ 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
+- **`creator_type`** 🧑‍🤝‍🤖 *Creator Type* - What kind of creator submitted the feedback: `'human'`, `'agent'`, or `'unknown'`.
 
 ## Rails Integration
 
@@ -100,7 +128,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 +138,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 +146,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 +163,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
@@ -154,7 +182,8 @@ end
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `api_key` | String | *required* | Your Coolhand API key for authentication |
+| `api_key` | String | `nil` | Your Coolhand API key. If absent, intercepted requests are skipped with a warning log rather than raising at boot time |
+| `enabled` | Boolean | `true` | Set to `false` to disable all patching and validation (e.g. `Rails.env.production?`) |
 | `silent` | Boolean | `false` | Whether to suppress console output |
 | `intercept_addresses` | Array | `["api.openai.com", "api.anthropic.com"]` | Array of API endpoint strings to monitor |
 
@@ -164,7 +193,7 @@ end
 
 ```ruby
 require 'openai'
-require 'coolhand/ruby'
+require 'coolhand'
 
 # Configure Coolhand
 Coolhand.configure do |config|
@@ -275,28 +304,26 @@ The monitor works with multiple transport layers and Ruby libraries:
 
 **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
 
-**Auto-detection**: Coolhand automatically detects which transport layer your libraries use and applies the appropriate monitoring strategy.
+**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
 
-Coolhand uses a dual-interceptor strategy to monitor different HTTP transport layers:
+Coolhand uses a unified Net::HTTP interceptor to monitor all HTTP traffic to configured LLM endpoints:
 
-### Faraday Interceptor
-- Patches Faraday connections using middleware injection
-- Monitors: OpenAI SDK, ruby-anthropic, LangChain.rb, and other Faraday-based libraries
-- Handles: Standard HTTP requests and Server-Sent Events (SSE) for streaming
-
-### Anthropic Interceptor
-- Patches the official Anthropic gem's internal HTTP transport (Net::HTTP)
-- Monitors: Official Anthropic Ruby SDK requests
+### 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
 
 ### 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 appropriate interceptor
+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
@@ -336,7 +363,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
@@ -365,6 +392,102 @@ 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
@@ -376,10 +499,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/docs/anthropic.md

@@ -15,7 +15,7 @@ Coolhand automatically detects which Anthropic gem you're using and applies the
 ### Basic Configuration
 
 ```ruby
-require 'coolhand/ruby'
+require 'coolhand'
 
 Coolhand.configure do |config|
   config.api_key = 'your_coolhand_api_key_here'
@@ -39,7 +39,7 @@ gem 'anthropic'
 
 ```ruby
 require 'anthropic'
-require 'coolhand/ruby'
+require 'coolhand'
 
 # Configure Coolhand
 Coolhand.configure do |config|
@@ -124,7 +124,7 @@ gem 'ruby-anthropic'
 
 ```ruby
 require 'ruby-anthropic'
-require 'coolhand/ruby'
+require 'coolhand'
 
 # Configure Coolhand
 Coolhand.configure do |config|
@@ -172,7 +172,7 @@ When both gems are installed, Coolhand automatically handles the conflict:
 ```ruby
 require 'anthropic'        # Official gem
 require 'ruby-anthropic'  # Community gem
-require 'coolhand/ruby'
+require 'coolhand'
 
 Coolhand.configure do |config|
   config.api_key = 'your_coolhand_api_key'
@@ -199,7 +199,7 @@ begin
   $LOAD_PATH.reject! { |path| path.include?('ruby-anthropic') }
 
   require 'anthropic'
-  require 'coolhand/ruby'
+  require 'coolhand'
 
   Coolhand.configure do |config|
     config.api_key = 'your_coolhand_api_key'
@@ -359,10 +359,10 @@ request_id = Thread.current[:coolhand_current_request_id]
 puts "Logged to Coolhand with ID: #{request_id}"
 
 # Use this ID for feedback or debugging
-feedback_service = Coolhand::Ruby::FeedbackService.new(Coolhand.configuration)
+feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
 feedback_service.create_feedback(
   llm_request_log_id: request_id,
-  like: true,
+  sentiment: "like",
   explanation: "Great response quality"
 )
 ```
@@ -380,7 +380,7 @@ Coolhand.configure do |config|
 end
 
 # Now you'll see console output like:
-# "✅ Coolhand ready - will log OpenAI and Anthropic (official gem) calls"
+# "✅ Coolhand ready - will log inference calls on monitored URIs"
 # "COOLHAND: ⚠️ Warning: Both 'anthropic' and 'ruby-anthropic' gems are installed..."
 ```
 
@@ -393,8 +393,8 @@ end
 **Solution**: Ensure you require the gem before configuring Coolhand:
 
 ```ruby
-require 'anthropic'  # Must come before coolhand/ruby
-require 'coolhand/ruby'
+require 'anthropic'  # Must come before coolhand
+require 'coolhand'
 
 Coolhand.configure do |config|
   config.api_key = 'your_api_key'
@@ -515,4 +515,4 @@ For complete API documentation, see:
 
 - **Coolhand Issues**: [GitHub Issues](https://github.com/Coolhand-Labs/coolhand-ruby/issues)
 - **Anthropic API**: [Anthropic Documentation](https://docs.anthropic.com/)
-- **Gem Conflicts**: Check this guide's troubleshooting section
+- **Gem Conflicts**: Check this guide's troubleshooting section

data/docs/elevenlabs.md

@@ -213,11 +213,12 @@ class TranscriptsController < ApplicationController
 
       if feedback_data
         # Submit feedback to Coolhand using llm_provider_unique_id for matching
+        rating = feedback_data[:feedback_rating]
         coolhand_feedback = {
-          like: feedback_data[:feedback_rating],
+          sentiment: rating.nil? ? nil : (rating ? "like" : "dislike"),
           explanation: feedback_data[:feedback_text],
           llm_provider_unique_id: conversation_id # Important: use this field for matching
-        }
+        }.compact
 
         result = Coolhand.feedback_service.create_feedback(coolhand_feedback)
 
@@ -392,11 +393,12 @@ response = service.fetch_conversation(conversation_id)
 feedback = service.extract_feedback(response)
 
 # Test Coolhand submission
+rating = feedback[:feedback_rating]
 coolhand_feedback = {
-  like: feedback[:feedback_rating],
+  sentiment: rating.nil? ? nil : (rating ? "like" : "dislike"),
   explanation: feedback[:feedback_text],
   llm_provider_unique_id: conversation_id
-}
+}.compact
 result = Coolhand.feedback_service.create_feedback(coolhand_feedback)
 ```