coolhand 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f66ea8b94e39769d66543c75987c2108397f89c93dc53748753b396ca76d921
-  data.tar.gz: 560b9ec89c71b31095b5f579bb270b295a79b87a7edbec495179f6f1b764f77e
+  metadata.gz: 25393afdf95625b624ca2910cb3017685705529e9628a5d15cb3bdffdf122d52
+  data.tar.gz: 3e478c3b8494d5fef5bc87896fbf69cb9f93d088029b9a9745563c9a789b4473
 SHA512:
-  metadata.gz: ebd806bb3744d3fd16673a98f7746b144b468a158ec855b32a4ba142cf110ff4a78b03ea1b95106b8f29d011425bbe0ec44b8f853acb87b9e4037cf87843991f
-  data.tar.gz: 3a8078f5dbe7f3a5c7a0892b391a7085d54b5a6aa1db386075e34470c89802ca0bd6bb5dc5654dffa7fcb2595da3df7b2210a52568595c5c77929e435d1a13b8
+  metadata.gz: ad635f9377f6cb81967fc24b0c2aa9f9938c41e308c6b98511ee0139b9938e01ea766baf72a085700866c69ac50207da11e29f04d30a94ad3b487d3e22243d9e
+  data.tar.gz: d6ef0baf4e37d29b36a0d7a2d6a41822f551a0a753a2dc963c0da9eed60b90bf29b5f0015caa8a628c6f340ec9cb2b3ef2c83ecb9b59fbcec909d70f396603df

data/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-08-02
+
+### Added
+- **`Coolhand::Vertex::BatchResultProcessor.new` accepts an optional `model:` keyword** (falls back to a `"model"` key in `batch_info` when omitted) to populate the `model` field on batch-result logs — included only when one of those is available and non-blank, and omitted from the payload entirely otherwise (#76).
+- **`Coolhand::BaseInterceptor.send_complete_request_log` accepts optional `source_api:`/`model:` keywords**, for synthetic/batch log types (like the Vertex processor above) that aren't backed by a real intercepted HTTP request (#76).
+
+### Changed
+- **Vertex batch results with a missing or malformed job resource name or unparseable `startTime`/`endTime` are no longer logged at all.** Previously the processor still sent a request log using whatever was in `batch_info["name"]` (even if blank), just with a broken URL. It now validates these fields and skips the log entirely — with a `Rails.logger.error` explaining why — rather than sending something unusable (#76).
+- **A batch whose `endTime` precedes its `startTime` (e.g. clock skew) is still logged**, with `duration_ms` clamped to `0` and a warning logged, rather than dropped — unlike the missing/malformed cases above, the request/response content itself is still valid here (#76).
+- **A Vertex batch result item that isn't a `Hash` with a `"request"` and/or `"response"` key is now rejected and logged as an error**, instead of being sent as a log with `nil` request/response bodies (#76).
+- **The published gem no longer packages `.claude/`, `.idea/`, or `CLAUDE.md`** — these are repo/agent tooling, not part of the library.
+
+### Security
+- **A webhook processing error no longer leaves the request authenticated by default.** `Coolhand::WebhookInterceptor#intercept_batch_request` previously logged and swallowed *any* exception (a malformed webhook secret, a non-Hash JSON payload, a bug in `process_event`), returning normally without halting the Rails `before_action` chain — so the controller action still ran for a request whose signature was never confirmed valid. It now calls `head :unauthorized` in that rescue, matching the existing invalid-signature path, and validates the parsed webhook payload is a `Hash` before use.
+- **A blank or whitespace-only OpenAI webhook secret is no longer usable as the HMAC key.** `Coolhand::OpenAi::WebhookValidator` previously only rejected `nil`/`false`, so `webhook_secret = ""` (e.g. an unset `ENV` var with a blank default) silently signed and verified requests with an empty key — a much weaker, easy-to-guess bypass than the already-known "secret not configured" path. It now uses the same `Coolhand.required_field?` blank-check used elsewhere in the gem.
+- **`Cookie`/`Set-Cookie` headers are now redacted**, alongside the existing key/token/secret/signature/authorization patterns. Forwarding a Rails session cookie (a bearer credential) to Coolhand — e.g. via `LoggerService#forward_webhook(headers: request.headers)`, the pattern this gem's own docs show — was previously possible.
+- **`BaseInterceptor.sanitize_url` now redacts a broader set of credential-shaped query parameters** (`sig`, `credential`, `password`, `auth`, in addition to the existing `key`/`token`/`secret`), matching the pattern-based approach already used for headers instead of a small exact-match list. This covers AWS SigV4 (`X-Amz-Signature`, `X-Amz-Credential`) and Google Cloud (`X-Goog-Signature`, `X-Goog-Credential`) presigned-URL parameters that were previously logged in full.
+- **A failure capturing an intercepted request's body (e.g. an already-consumed `body_stream`) no longer prevents the real request from being attempted.** The capture happened before any error handling was in place, so an exception there escaped `NetHttpInterceptor#request` entirely — the host app's actual LLM call never happened. It's now rescued, logged, and treated as "body unavailable," and the real request still proceeds.
+- **Streamed response bodies are no longer buffered into a thread-local for requests this gem never intercepted.** `ResponseInterceptor#read_body` previously buffered every block-form `read_body` call process-wide, regardless of whether the enclosing request matched `intercept_addresses` — an unbounded memory growth path on any thread that streams large non-LLM responses (file downloads, etc.). Buffering now only happens while a `NetHttpInterceptor#request` call is actively capturing.
+- **A request made from inside another intercepted request's streaming callback no longer corrupts the outer request's logged response body.** The per-thread stream buffer is now saved and restored around each intercepted request instead of unconditionally cleared, so nested/reentrant LLM calls (e.g. a second provider call triggered from a chunk handler) no longer mix one request's content into another's log entry.
+- **Coolhand's own request to its backend API is no longer re-intercepted and re-logged.** If a self-hosted `base_url` or custom `intercept_addresses` entry happens to match Coolhand's own API host, the log-shipping request itself would previously be captured and logged like any other request — which itself gets logged, recursively, without bound. It's now wrapped in `Coolhand.without_capture`.
+- `Coolhand::OpenAi::WebhookValidator#webhook_secret` is no longer a public reader (it's only used internally) — reduces the chance of the raw secret ending up in error-tracker breadcrumbs or view-rendered controller state.
+- `YAML.load_file` → `YAML.safe_load_file` for the gem's own bundled default-addresses/patterns YAML files — defense-in-depth against unsafe deserialization, consistent with modern Psych defaults.
+- Added missing `require "openssl"` (`WebhookValidator`) and `require "stringio"` (`NetHttpInterceptor`) instead of relying on both being transitively loaded by something else first.
+
+### Fixed
+- **Vertex batch result logging** — `Coolhand::Vertex::BatchResultProcessor` now sends a fully-qualified URL (`https://aiplatform.googleapis.com/v1/<resource name>`) instead of the bare Vertex job resource name, plus explicit `source_api` and `model` values, all inside `raw_request`. The Coolhand API treats `raw_request` as free-form JSON, so this improves the data available to its classification without depending on new top-level payload fields being accepted. Also fixed: `timestamp`/`completed_at` are now sent as proper ISO 8601 strings instead of raw `Time` objects, and the URL is now run through the same `sanitize_url` helper used by every other logging path in the gem, for consistency (a Vertex batch URL can't actually carry a redactable query string today, so this is defense-in-depth rather than a fix for a live leak) (#76).
+- **`require "coolhand"` no longer requires `faraday`.** The gem hasn't used Faraday directly since the 0.4.0 unified `NetHttpInterceptor`, but a stale top-level `require "faraday"` meant loading the gem could raise `LoadError` for anyone without faraday installed — it was never a declared dependency. If your app relied on `require "coolhand"` transitively loading Faraday, require it yourself.
+- `Coolhand::Vertex::BatchResultProcessor`, `Coolhand::OpenAi::BatchResultProcessor`, and `Coolhand::OpenAi::WebhookValidator` can now each be required independently (e.g. `require "coolhand/vertex/batch_result_processor"`) without first requiring `"coolhand"` — previously this could raise `NameError` depending on load order.
+- `Coolhand::BaseInterceptor.send_complete_request_log` now runs `request_headers`/`response_headers` through `sanitize_headers` itself, rather than trusting every caller to have pre-sanitized them. `NetHttpInterceptor` already sanitized before calling it (`sanitize_headers` is idempotent, so no behavior change there); this closes the gap for any future caller that forgets.
+- `Coolhand::Vertex::BatchResultProcessor#handle_failed_batch` no longer raises `NoMethodError` when a failed batch's `error` field is missing or not a Hash — it now logs the batch-failure message either way instead of falling through to the generic "failed to process" catch-all.
+- **README's "Request Flow" section corrected** — it previously claimed data is sent to the Coolhand API "asynchronously in a background thread" with "zero performance impact"; it's actually sent inline, after the original response is available, bounded by the 5-second timeout described in 0.5.0's Security section.
+
+## [0.5.0] - 2026-07-30
+
+### Changed
+- **`llm_request_log_id` and `workload_id` in feedback API responses are now hashid strings, not raw integers** — the Coolhand API now returns these as hashids, matching every other external-facing identifier on the record (they previously leaked the raw integer foreign key). This gem never typed or coerced these fields (plain hashes throughout), so no code changes are required here, but if your application stores or compares `result[:llm_request_log_id]` or `result[:workload_id]` as an integer, update it to treat the value as an opaque string identifier instead. The `create_feedback`/`update_feedback` input fields (`llm_request_log_id`, `workload_hashid`) are unaffected — they still accept either a raw integer or a hashid string.
+- **`id` in feedback API responses has actually been a hashid string for some time** — flagging here since it's the same category of field; no gem-level change needed since this was never typed.
+- `BaseInterceptor.sanitize_headers` and `LoggerService#sanitize_headers` (used for the main request/response logging path and webhook forwarding, respectively) now share the same sensitive-header pattern instead of each maintaining its own list, so both paths redact consistently.
+
+### Security
+- **AWS Bedrock SigV4 session tokens (`X-Amz-Security-Token`) are now redacted before logging.** The interceptor's header sanitizer used a hardcoded list of known API-key header names (`api-key`, `x-api-key`, `x-goog-api-key`, `openai-api-key`) instead of a general pattern, so this header — present on requests signed with temporary/STS credentials, the common case for Bedrock — was forwarded to the Coolhand backend and printed in `debug_mode` unredacted. The sanitizer now redacts any header whose name matches `key`, `token`, `secret`, `signature`, or `authorization`, closing this and similar gaps for any current or future provider header.
+- **`debug_mode`'s "skipping capture" log line no longer prints the raw URL.** When a request matched `exclude_api_patterns` while `debug_mode` was on, the log line bypassed the usual URL sanitizer, so a Gemini/Vertex `?key=...` query-param API key could be printed in full. It now goes through the same URL sanitizer as every other log line.
+- **Outbound requests to the Coolhand backend now set a 5-second connect/read timeout.** Previously this call had no explicit timeout and ran inline on the same thread as the intercepted LLM request, so a slow or unreachable Coolhand endpoint (including a self-hosted `base_url`) could add Ruby's ~60s Net::HTTP default (up to ~120s total) of latency to real LLM calls made by the host app.
+
+### Removed
+- Deleted unused `BaseInterceptor` methods with no callers anywhere in the gem: `extract_response_data`, `extract_usage_metadata`, `clean_request_headers`, `clean_response_headers`. The latter two duplicated `sanitize_headers` with a narrower, case-sensitive header list and were never wired into any interceptor — dead code carrying its own security debt.
+
+### Dependencies
+- Bumped `faraday` from 2.14.2 to 2.14.3 (#73).
+
 ## [0.4.0] - 2026-06-22
 
 ### Added

data/README.md

@@ -2,7 +2,9 @@
 
 [![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.
+Monitor and log LLM API calls — OpenAI, Anthropic, Google Gemini, Cohere, and any Faraday-based or Net::HTTP client — to the Coolhand analytics platform. Supports Ruby LLM monitoring, request logging, and feedback collection.
+
+> **Scope**: Coolhand intercepts outgoing HTTP requests to configured LLM API endpoints only. It does not read, scan, or transmit your source code files.
 
 ## Installation
 
@@ -37,38 +39,21 @@ end
 # ✅ OpenAI SDK calls
 # ✅ Anthropic API calls
 # ✅ Direct HTTP requests to AI APIs
-# ✅ ANY library making AI API calls via Faraday
+# ✅ Any library making AI API calls via Faraday's default adapter
 
 # NO code changes needed in your existing services!
 ```
 
 **✨ Why Automatic Monitoring:**
 - 🚫 **Zero refactoring** - No code changes to existing services
-- 📊 **Complete coverage** - Monitors ALL AI libraries using Faraday automatically
+- 📊 **Complete coverage** - Monitors AI libraries using Net::HTTP or Faraday's default adapter automatically
 - 🔒 **Security built-in** - Automatic credential sanitization
 - ⚡ **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.
+Point the SDK at your own Coolhand-compatible endpoint via `config.base_url` for compliance or data-residency requirements. See [Self-Hosted Deployments →](docs/configuration.md).
 
 ## Feedback API
 
@@ -80,10 +65,10 @@ Collect feedback on LLM responses to improve model performance.
 require 'coolhand'
 
 # Create feedback for an LLM response
-feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
+feedback_service = Coolhand::FeedbackService.new
 
 feedback = feedback_service.create_feedback(
-  llm_request_log_id: 123,
+  llm_request_log_id: 'abc123def456', # hashid from a prior response; a raw integer FK also still works
   llm_provider_unique_id: 'req_xxxxxxx',
   client_unique_id: 'workorder-chat-456',
   creator_unique_id: 'user-789',
@@ -94,22 +79,7 @@ feedback = feedback_service.create_feedback(
 )
 ```
 
-**Field Guide:** All fields are optional, but here's how to get the best results:
-
-### Matching Fields
-- **`llm_request_log_id`** 🎯 *Exact Match* - ID from the Coolhand API response when the original LLM request was logged. Provides exact matching.
-- **`llm_provider_unique_id`** 🎯 *Exact Match* - The x-request-id from the LLM API response (e.g., "req_xxxxxxx")
-- **`original_output`** 🔍 *Fuzzy Match* - The original LLM response text. Provides fuzzy matching but isn't 100% reliable.
-- **`client_unique_id`** 🔗 *Your Internal Matcher* - Connect to an identifier from your system for internal matching
-
-### 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.
-- **`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'`.
+For a full field reference and matching strategy, see [Feedback API →](docs/feedback.md).
 
 ## Rails Integration
 
@@ -138,7 +108,7 @@ end
 ```ruby
 class ChatController < ApplicationController
   def create_feedback
-    feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
+    feedback_service = Coolhand::FeedbackService.new
 
     feedback = feedback_service.create_feedback(
       llm_request_log_id: params[:log_id],
@@ -163,7 +133,7 @@ end
 ```ruby
 class FeedbackCollectionJob < ApplicationJob
   def perform(feedback_data)
-    feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
+    feedback_service = Coolhand::FeedbackService.new
 
     feedback_service.create_feedback(
       llm_provider_unique_id: feedback_data[:request_id],
@@ -184,6 +154,7 @@ end
 |--------|------|---------|-------------|
 | `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?`) |
+| `capture` | Boolean | `true` | Whether to capture and forward intercepted requests. Set to `false` to monitor without forwarding, then use [`Coolhand.with_capture`](#selective-capture) to re-enable selectively |
 | `silent` | Boolean | `false` | Whether to suppress console output |
 | `intercept_addresses` | Array | `["api.openai.com", "api.anthropic.com"]` | Array of API endpoint strings to monitor |
 
@@ -217,6 +188,38 @@ puts response.dig("choices", 0, "message", "content")
 
 📖 **[Complete Anthropic Integration Guide →](docs/anthropic.md)** - Supports both official and community gems with automatic detection
 
+### Selective Capture
+
+Use `Coolhand.with_capture` and `Coolhand.without_capture` to override the global `capture` setting for a specific block of code, without changing your configuration.
+
+**Capture a specific call when capture is globally disabled:**
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key = 'your_api_key_here'
+  config.capture = false  # disabled globally
+end
+
+Coolhand.with_capture do
+  response = openai_client.chat(parameters: {
+    model: "gpt-4o-mini",
+    messages: [{ role: "user", content: "Hello!" }],
+  })
+  # This request is captured and forwarded to Coolhand
+end
+```
+
+**Skip capture for a specific call when capture is globally enabled:**
+
+```ruby
+Coolhand.without_capture do
+  response = openai_client.chat(parameters: { ... })
+  # This request is NOT forwarded to Coolhand
+end
+```
+
+Both methods are thread-safe. Blocks nest correctly — the innermost block takes precedence, and the outer setting is restored when the block exits.
+
 ## 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:
@@ -294,39 +297,45 @@ The filtering is automatic and applies to all monitored API calls and webhook lo
 
 The monitor works with multiple transport layers and Ruby libraries:
 
-**Faraday-based libraries:**
+**Faraday-based libraries** (via Faraday's default `net_http` adapter — a non-Net::HTTP adapter such as `faraday-typhoeus` is not covered):
 - OpenAI Ruby SDK
 - ruby-anthropic gem (community Anthropic gem)
 - ruby-openai gem
 - LangChain.rb
-- Direct Faraday requests
-- Any other Faraday-based HTTP client
+- Direct Faraday requests using the default adapter
 
 **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
 
+**Other providers monitored out of the box:**
+- Google Gemini (`generativelanguage.googleapis.com`)
+- Google Vertex AI (`aiplatform.googleapis.com`) — see the [Vertex AI batch result logging guide](docs/vertex.md) for async batch jobs
+- AWS Bedrock (OpenAI-compatible endpoint)
+- Cloudflare AI Gateway
+- OpenRouter
+
 **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 unified Net::HTTP interceptor to monitor all HTTP traffic to configured LLM endpoints:
+Coolhand uses a unified Net::HTTP interceptor to capture outgoing requests to configured LLM API 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)
+- Extends Ruby's `Net::HTTP` using `Module#prepend` (a standard Ruby technique for wrapping library behavior)
+- Covers HTTP libraries that delegate to 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
+1. The original request executes normally
 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
+4. Data is sent to the Coolhand API inline, after the original response is available (bounded by a 5-second connect/read timeout so a slow or unreachable Coolhand backend can't hang your request indefinitely)
+5. Your application continues once the log is sent (or times out) — the original request/response is never blocked on Coolhand being reachable
 
 For non-matching endpoints, requests pass through unchanged.
 
@@ -392,106 +401,14 @@ 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
 
+## Documentation
 
-## 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
+- **[Configuration](docs/configuration.md)** — Self-hosted deployments, base_url rules, debug mode, custom intercept addresses
+- **[Feedback API](docs/feedback.md)** — Full field reference, matching strategies, sentiment values
+- **[Anthropic Integration](docs/anthropic.md)** — Official and community Anthropic Ruby gems, streaming, dual gem handling, and troubleshooting
+- **[ElevenLabs Integration](docs/elevenlabs.md)** — Webhook capture, feedback submission, and Rails integration
+- **[OpenAI Batch Webhook Handler](docs/openai.md)** — Handle OpenAI batch job completion events via webhook interception
+- **[Google Vertex AI Batch Result Logging](docs/vertex.md)** — Log completed Vertex AI batch prediction job results
 
 ## Security
 
@@ -511,6 +428,10 @@ end
 - **Contribute?** [Submit a pull request](https://github.com/Coolhand-Labs/coolhand-ruby/pulls)
 - **Support?** Visit [coolhandlabs.com](https://coolhandlabs.com)
 
+## About Coolhand Labs
+
+Coolhand Labs builds LLM observability and feedback tooling so teams can monitor, understand, and improve their AI applications. Learn more at [coolhandlabs.com](https://coolhandlabs.com).
+
 ## License
 
 Apache-2.0

data/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest published version of `coolhand` on RubyGems is supported with security fixes.
+Please upgrade to the latest version before reporting an issue.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities.
+
+Instead, report vulnerabilities privately using one of the following:
+
+- [GitHub Security Advisories](https://github.com/Coolhand-Labs/coolhand-ruby/security/advisories/new)
+  for this repository (preferred)
+- Email team@coolhandlabs.com
+
+Please include a description of the vulnerability, steps to reproduce, and the impact you believe
+it has. We aim to acknowledge reports within 3 business days and to provide a fix or mitigation
+plan within 30 days, depending on severity.

data/docs/configuration.md

@@ -0,0 +1,59 @@
+# Advanced Configuration
+
+## 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.
+
+**URL validation rules:**
+- Any `https://` URL — required for production use
+- `http://localhost` or `http://127.0.0.1` — accepted for local development only
+- Non-HTTPS remote URLs are rejected: the SDK raises `Coolhand::Error` at configure time if `base_url` is set to a plain `http://` URL pointing at a non-localhost host
+
+**Trailing slashes** are stripped automatically, so `"https://example.com/api/"` and `"https://example.com/api"` are equivalent.
+
+---
+
+## Debug Mode
+
+`config.debug_mode` is a local-development aid: it prints every prepared payload to the console instead of sending it to the Coolhand API (or your self-hosted `base_url`), so you can inspect exactly what would be logged without an API key or network access.
+
+```ruby
+Coolhand.configure do |config|
+  config.debug_mode = Rails.env.development?
+end
+```
+
+**What changes when `debug_mode` is `true`:**
+- No HTTP request is made — `create_log`, `create_feedback`, and `send_llm_request_log` all return `nil` and print the payload via `JSON.pretty_generate` instead.
+- Capture is forced on for every request, including inside a `Coolhand.without_capture` block and when `config.capture = false`. This is intentional — debug mode is meant to show you everything, not respect capture suppression — so don't leave it enabled in an environment where you rely on `without_capture` to keep specific calls out of the logs.
+- Header and URL sanitization (`[REDACTED]` API keys/tokens, redacted `key=`/`token=` query params) still applies to the printed payload, exactly as it would to a real request.
+
+Because it forces capture unconditionally and prints full request/response bodies to the console, only enable `debug_mode` in development — never in production or in an environment handling real user data.
+
+## Custom Intercept Addresses
+
+By default Coolhand captures requests to a built-in list of LLM API hosts (OpenAI, Anthropic, Google Gemini, ElevenLabs, GitHub Models, and more). To capture a custom endpoint — an internal proxy, a self-hosted model server, or a third-party gateway — override `intercept_addresses`:
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key = ENV['COOLHAND_API_KEY']
+  config.intercept_addresses = [
+    'my-llm-proxy.internal',
+    'api.openai.com',      # include the defaults you still want
+    'api.anthropic.com',
+  ]
+end
+```
+
+Setting `intercept_addresses` **replaces** the default list entirely, so include any default hosts you still need.
+
+The default list can be found in `Coolhand::Configuration::DEFAULT_INTERCEPT_ADDRESSES`.

data/docs/feedback.md

@@ -0,0 +1,79 @@
+# Feedback API
+
+Collect user feedback on LLM responses to improve your AI outputs. The Feedback API lets you capture sentiment ratings, explanations, and human-corrected outputs.
+
+> **Frontend widget:** For browser-based feedback collection, see [coolhand-js](https://github.com/Coolhand-Labs/coolhand-js) — a lightweight JavaScript widget that captures actionable user feedback on any AI output.
+
+## Basic Usage
+
+```ruby
+require 'coolhand'
+
+feedback_service = Coolhand::FeedbackService.new
+
+# Positive feedback linked by log ID (most reliable)
+feedback_service.create_feedback(
+  llm_request_log_id: 'abc123def456', # hashid from a prior response; a raw integer FK also still works
+  sentiment: 'like',
+  explanation: 'Clear and accurate answer.',
+)
+
+# Negative feedback with a human correction
+feedback_service.create_feedback(
+  original_output: 'The capital of France is London.',
+  sentiment: 'dislike',
+  revised_output: 'The capital of France is Paris.',
+  explanation: 'Factually wrong.',
+)
+```
+
+---
+
+## Field Reference
+
+All fields are optional. Use at least one **Matching Field** to link feedback to its originating LLM request.
+
+### Matching Fields
+
+These fields identify which LLM request the feedback refers to. Use the most specific one available.
+
+| Field | Match type | Description |
+|---|---|---|
+| `llm_request_log_id` | Exact | Hashid returned when the original request was logged (a raw integer FK is also still accepted for backward compatibility). Most reliable. |
+| `llm_provider_unique_id` | Exact | The provider's own request ID (e.g. `x-request-id` from Anthropic or OpenAI). |
+| `client_unique_id` | Exact | Your own internal identifier for the request (e.g. a database row ID). |
+| `original_output` | Fuzzy | The raw text the LLM produced. Used for fuzzy matching when no ID is available — less reliable. |
+
+### Quality Signals
+
+| Field | Signal strength | Description |
+|---|---|---|
+| `revised_output` | ⭐ Best | The human-corrected version of the LLM output. Highest-value signal for quality improvement. |
+| `explanation` | Medium | Free-text reason the response was good or bad. |
+| `sentiment` | Low–Medium | `"like"`, `"dislike"`, or `"neutral"`. **Preferred** over the deprecated `like` boolean. |
+| `like` | Low (deprecated) | Boolean: `true` = like, `false` = dislike. Auto-converted to `sentiment` before submission. Use `sentiment` instead. |
+
+### Attribution Fields
+
+| Field | Description |
+|---|---|
+| `creator_unique_id` | ID of the user providing feedback (for per-user quality tracking). |
+| `creator_type` | Who submitted the feedback: `"human"`, `"agent"`, or `"unknown"`. |
+| `workload_hashid` | Associate feedback with a specific workload in the Coolhand dashboard. |
+
+---
+
+## Sentiment Values
+
+| Value | Meaning |
+|---|---|
+| `"like"` | The response was helpful / correct |
+| `"dislike"` | The response was unhelpful / wrong |
+| `"neutral"` | Neither good nor bad (e.g. factual but irrelevant) |
+
+The deprecated `like: bool` field is still accepted and automatically converted:
+
+| `like` (bool) | Equivalent `sentiment` |
+|---|---|
+| `true` | `"like"` |
+| `false` | `"dislike"` |

data/docs/openai.md

@@ -0,0 +1,60 @@
+# OpenAI Batch Webhook Handler
+
+Automatically handle OpenAI batch event logs (`batch.completed`, `batch.failed`, `batch.expired`, `batch.cancelled`) by intercepting webhook requests and logging completed batch results to Coolhand.
+
+For monitoring regular (non-batch) OpenAI API calls, see the [OpenAI client example](../README.md#with-openai-ruby-client) in the main README — no extra setup is required beyond `Coolhand.configure`.
+
+Requires Rails — `Coolhand::WebhookInterceptor` and `Coolhand::OpenAi::BatchResultProcessor` log via `Rails.logger` internally. `config.capture = false` and `Coolhand.without_capture` do not suppress these logs: unlike the passive Net::HTTP interceptor, `intercept_batch_request` dispatching to `Coolhand::OpenAi::BatchResultProcessor` is an explicit, deliberate act, so it always sends.
+
+## Usage
+
+- Add the `openai` gem to your Gemfile — `Coolhand::OpenAi::BatchResultProcessor` needs it to download batch result files.
+- Include the interceptor in your controller: `include Coolhand::WebhookInterceptor`
+- Add the `before_action` to validate and populate the `@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
+
+`intercept_batch_request` already validates the webhook and, for `batch.completed`/`batch.failed`/`batch.expired`/`batch.cancelled` events, calls `Coolhand::OpenAi::BatchResultProcessor` **synchronously**, inline in the `before_action` — that part requires no code in your controller action. It downloads two JSONL files from OpenAI and sends one request log per batch item, so a large batch can take long enough to trip your webhook endpoint's timeout (and OpenAI's retry behavior); consider that when sizing batches. The example below shows a controller action doing additional, app-specific work on top of that (e.g. updating your own `BatchApiRequest` record and enqueuing your own background job), which is optional.
+
+## Minimal example
+
+Only the key lines are shown — wire this into your own controller and background job setup.
+
+```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
+      MyApp::BatchResultJob.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...
+```