coolhand 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04f5762e1c9b3dad57c3b65fbe6860a0394fd793f49e67538eaf8c68584ccae5
-  data.tar.gz: d666c068c33af71f895228030d6342008ccdae290de4c603dec687cf07b5645d
+  metadata.gz: fc0fc356a6cf69d4a0c67a906000cab9590d9fc2a452efec8037a7f541efa561
+  data.tar.gz: ec6f7a136ae1d8e139bf638175b81a2dda063b9bf19d0199ab7f7135cf6d833d
 SHA512:
-  metadata.gz: 4a9de9973617ef1a0816811a5d29dc43ebdda8eb11540474d15e350670a675f4826ff6d9eac56aad5e82dbebdeb50a812ab8bc96d8a16a9f522d27294e6f8035
-  data.tar.gz: 382033854564a57ced160afad00bec423d551a2aaeda70a69cfc9a1a2eaf83843dfe6c3479ca3733ff71a436516032a06c0d1b7dc7f8bc937bd49e5376f51049
+  metadata.gz: 131465dcaf94ae8cc4b5dce47252fe92effc9693ba4de6e61247714c682a717934fa3144cf3228bf754fe89a53803051f32a895c3a42fd3c07990d4cf74286a5
+  data.tar.gz: 26e03d0f27b9acbeb36ff6a0e0ee11cca55b8142cd17d494972013534ba4d8b3753b29fb3565dedb8c0f8daf1e26d7af443353999f5956f5b1b7b8d7ea139585

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

data/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.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

data/README.md

@@ -186,29 +186,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 +263,43 @@ 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)
+- Any library using Net::HTTP directly
+
+**Auto-detection**: Coolhand automatically detects which transport layer your libraries use and applies the appropriate monitoring strategy.
+
 ## How It Works
 
-The gem patches Faraday connections to intercept HTTP requests. When a request matches the configured LLM endpoints:
+Coolhand uses a dual-interceptor strategy to monitor different HTTP transport layers:
+
+### 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
+
+### Request Flow
+When a request matches configured LLM endpoints:
 
-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
+1. The original request executes normally with zero performance impact
+2. Request and response data (body, headers, status) are captured by the appropriate 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.
 
@@ -369,6 +367,7 @@ The monitor handles errors gracefully:
 
 ## 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

data/docs/anthropic.md

@@ -0,0 +1,518 @@
+# Anthropic Integration Guide
+
+Coolhand provides comprehensive monitoring for Anthropic's Claude API through support for both the official and community Ruby gems. This guide covers setup, usage, streaming, and troubleshooting.
+
+## Overview
+
+Coolhand automatically detects which Anthropic gem you're using and applies the appropriate monitoring strategy:
+
+- **Official Anthropic Gem** (`anthropic`): Uses Net::HTTP transport, monitored via AnthropicInterceptor
+- **Community Ruby-Anthropic Gem** (`ruby-anthropic`): Uses Faraday transport, monitored via FaradayInterceptor
+- **Dual Installation**: Automatically handles conflicts and prevents duplicate logging
+
+## Quick Start
+
+### Basic Configuration
+
+```ruby
+require 'coolhand/ruby'
+
+Coolhand.configure do |config|
+  config.api_key = 'your_coolhand_api_key_here'
+  config.silent = true  # Set to false for debug output
+end
+```
+
+That's it! All Anthropic API calls are now automatically monitored.
+
+## Official Anthropic Gem
+
+### Installation
+
+```bash
+gem install anthropic
+# or add to Gemfile
+gem 'anthropic'
+```
+
+### Basic Usage
+
+```ruby
+require 'anthropic'
+require 'coolhand/ruby'
+
+# Configure Coolhand
+Coolhand.configure do |config|
+  config.api_key = 'your_coolhand_api_key'
+end
+
+# Use official Anthropic gem normally
+client = Anthropic::Client.new
+
+response = client.messages(
+  parameters: {
+    model: "claude-3-sonnet-20240229",
+    max_tokens: 1024,
+    messages: [{ role: "user", content: "Hello, Claude!" }]
+  }
+)
+
+puts response.content.first.text
+# ✅ Request and response automatically logged to Coolhand
+```
+
+### Streaming with Official Gem
+
+```ruby
+# Streaming is automatically detected and properly logged
+response = client.messages(
+  parameters: {
+    model: "claude-3-sonnet-20240229",
+    max_tokens: 1024,
+    messages: [{ role: "user", content: "Write a haiku about Ruby" }],
+    stream: true  # ✅ Streaming automatically detected
+  }
+)
+
+# Process streaming response
+accumulated_text = ""
+response.each do |chunk|
+  if chunk.delta&.text
+    print chunk.delta.text
+    accumulated_text += chunk.delta.text
+  end
+end
+
+# ✅ Complete accumulated response logged to Coolhand (not individual chunks)
+```
+
+### Advanced Configuration
+
+```ruby
+client = Anthropic::Client.new
+
+# All parameters are automatically captured and logged
+response = client.messages(
+  parameters: {
+    model: "claude-3-opus-20240229",
+    max_tokens: 2000,
+    temperature: 0.7,
+    top_p: 0.9,
+    system: "You are a helpful assistant specializing in Ruby programming.",
+    messages: [
+      { role: "user", content: "Explain Ruby metaprogramming" }
+    ],
+    # Streaming works automatically
+    stream: true
+  }
+)
+
+# ✅ All parameters (model, temperature, top_p, system, etc.) logged
+```
+
+## Community Ruby-Anthropic Gem
+
+### Installation
+
+```bash
+gem install ruby-anthropic
+# or add to Gemfile
+gem 'ruby-anthropic'
+```
+
+### Basic Usage
+
+```ruby
+require 'ruby-anthropic'
+require 'coolhand/ruby'
+
+# Configure Coolhand
+Coolhand.configure do |config|
+  config.api_key = 'your_coolhand_api_key'
+end
+
+# Use ruby-anthropic gem normally - monitored via Faraday
+client = Anthropic::Client.new(access_token: ENV['ANTHROPIC_API_KEY'])
+
+response = client.messages(
+  model: "claude-3-sonnet-20240229",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Hello, Claude!" }]
+)
+
+puts response.dig("content", 0, "text")
+# ✅ Automatically logged via FaradayInterceptor
+```
+
+### Streaming with Ruby-Anthropic
+
+```ruby
+# Streaming works seamlessly via Faraday monitoring
+response = client.messages(
+  model: "claude-3-sonnet-20240229",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Count to 10 slowly" }],
+  stream: true
+)
+
+# Process Server-Sent Events
+response.each do |event|
+  puts event if event.start_with?("data:")
+end
+
+# ✅ Complete conversation logged to Coolhand
+```
+
+## Dual Gem Installation
+
+### Automatic Conflict Resolution
+
+When both gems are installed, Coolhand automatically handles the conflict:
+
+```ruby
+require 'anthropic'        # Official gem
+require 'ruby-anthropic'  # Community gem
+require 'coolhand/ruby'
+
+Coolhand.configure do |config|
+  config.api_key = 'your_coolhand_api_key'
+end
+
+# ⚠️  Warning displayed:
+# "Both 'anthropic' and 'ruby-anthropic' gems are installed.
+#  Coolhand will only monitor ruby-anthropic (Faraday-based) requests.
+#  Official anthropic gem monitoring has been disabled."
+```
+
+**Recommendation**: Use only one gem to avoid confusion. Choose based on your needs:
+- **Official gem**: Latest features, official support, Net::HTTP transport
+- **Community gem**: Faraday-based, may have community contributions
+
+### Manual Conflict Resolution
+
+To explicitly use the official gem when both are installed:
+
+```ruby
+# Temporarily hide the community gem
+begin
+  # Remove ruby-anthropic from the load path
+  $LOAD_PATH.reject! { |path| path.include?('ruby-anthropic') }
+
+  require 'anthropic'
+  require 'coolhand/ruby'
+
+  Coolhand.configure do |config|
+    config.api_key = 'your_coolhand_api_key'
+  end
+
+  # Now only the official gem will be monitored
+  client = Anthropic::Client.new
+  # ... use official gem
+end
+```
+
+## Rails Integration
+
+### Initializer Setup
+
+```ruby
+# config/initializers/coolhand.rb
+Coolhand.configure do |config|
+  # Use Rails credentials for API key
+  config.api_key = Rails.application.credentials.coolhand_api_key
+
+  # Suppress console output in production
+  config.silent = Rails.env.production?
+
+  # Ensure Anthropic endpoints are monitored (default behavior)
+  # config.intercept_addresses = ["api.openai.com", "api.anthropic.com"]
+end
+```
+
+### Service Object Pattern
+
+```ruby
+# app/services/claude_chat_service.rb
+class ClaudeChatService
+  def initialize
+    @client = Anthropic::Client.new
+  end
+
+  def generate_response(user_message, context: nil)
+    messages = []
+    messages << { role: "system", content: context } if context
+    messages << { role: "user", content: user_message }
+
+    response = @client.messages(
+      parameters: {
+        model: "claude-3-sonnet-20240229",
+        max_tokens: 1500,
+        messages: messages
+      }
+    )
+
+    response.content.first.text
+    # ✅ Automatically logged to Coolhand with all context
+  end
+
+  def stream_response(user_message)
+    response = @client.messages(
+      parameters: {
+        model: "claude-3-sonnet-20240229",
+        max_tokens: 1500,
+        messages: [{ role: "user", content: user_message }],
+        stream: true
+      }
+    )
+
+    Enumerator.new do |yielder|
+      response.each do |chunk|
+        if chunk.delta&.text
+          yielder << chunk.delta.text
+        end
+      end
+    end
+    # ✅ Complete streaming conversation logged
+  end
+end
+```
+
+### Background Job Example
+
+```ruby
+# app/jobs/claude_analysis_job.rb
+class ClaudeAnalysisJob < ApplicationJob
+  def perform(document_id, analysis_type)
+    document = Document.find(document_id)
+
+    client = Anthropic::Client.new
+
+    response = client.messages(
+      parameters: {
+        model: "claude-3-opus-20240229",
+        max_tokens: 2000,
+        system: "You are an expert document analyzer.",
+        messages: [
+          {
+            role: "user",
+            content: "Analyze this document: #{document.content}"
+          }
+        ]
+      }
+    )
+
+    document.update!(
+      analysis: response.content.first.text,
+      analysis_type: analysis_type
+    )
+
+    # ✅ Analysis request logged with document context
+  end
+end
+```
+
+## Advanced Features
+
+### Thread-Safe Concurrent Requests
+
+```ruby
+# Coolhand handles concurrent requests safely
+threads = []
+
+10.times do |i|
+  threads << Thread.new do
+    client = Anthropic::Client.new
+
+    response = client.messages(
+      parameters: {
+        model: "claude-3-sonnet-20240229",
+        max_tokens: 500,
+        messages: [{ role: "user", content: "Request #{i}" }]
+      }
+    )
+
+    puts "Response #{i}: #{response.content.first.text}"
+  end
+end
+
+threads.each(&:join)
+# ✅ All 10 requests logged correctly without conflicts
+```
+
+### Request Correlation
+
+Access the current request ID for correlation:
+
+```ruby
+client = Anthropic::Client.new
+
+response = client.messages(
+  parameters: {
+    model: "claude-3-sonnet-20240229",
+    max_tokens: 1000,
+    messages: [{ role: "user", content: "Hello" }]
+  }
+)
+
+# Get the request ID that was logged to Coolhand
+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.create_feedback(
+  llm_request_log_id: request_id,
+  like: true,
+  explanation: "Great response quality"
+)
+```
+
+## Troubleshooting
+
+### Debug Mode
+
+Enable verbose logging to see what's being intercepted:
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key = 'your_api_key'
+  config.silent = false  # Enable debug output
+end
+
+# Now you'll see console output like:
+# "✅ Coolhand ready - will log OpenAI and Anthropic (official gem) calls"
+# "COOLHAND: ⚠️ Warning: Both 'anthropic' and 'ruby-anthropic' gems are installed..."
+```
+
+### Common Issues
+
+#### 1. Gem Not Detected
+
+**Problem**: Coolhand says "Anthropic gem not loaded"
+
+**Solution**: Ensure you require the gem before configuring Coolhand:
+
+```ruby
+require 'anthropic'  # Must come before coolhand/ruby
+require 'coolhand/ruby'
+
+Coolhand.configure do |config|
+  config.api_key = 'your_api_key'
+end
+```
+
+#### 2. Duplicate Requests
+
+**Problem**: Seeing requests logged twice in dashboard
+
+**Cause**: Usually indicates both gems are installed and conflicting
+
+**Solution**: Choose one gem and uninstall the other:
+
+```bash
+# Keep official gem
+gem uninstall ruby-anthropic
+
+# OR keep community gem
+gem uninstall anthropic
+```
+
+#### 3. Missing Streaming Data
+
+**Problem**: Only seeing individual chunks, not complete response
+
+**Cause**: Custom streaming handling interfering with automatic detection
+
+**Solution**: Let Coolhand handle streaming automatically:
+
+```ruby
+# ❌ Don't manually collect chunks for logging
+response = client.messages(parameters: { stream: true })
+manual_collection = ""
+response.each { |chunk| manual_collection += chunk.delta.text }
+
+# ✅ Just process chunks normally - Coolhand handles logging
+response = client.messages(parameters: { stream: true })
+response.each { |chunk| print chunk.delta.text }
+```
+
+#### 4. Performance Concerns
+
+**Problem**: Worried about monitoring overhead
+
+**Solution**: Monitoring is asynchronous and negligible:
+
+```ruby
+# Monitoring happens in background threads
+# Your application performance is unaffected
+require 'benchmark'
+
+time = Benchmark.measure do
+  1000.times do
+    client.messages(
+      parameters: {
+        model: "claude-3-haiku-20240307",  # Fast model for testing
+        max_tokens: 100,
+        messages: [{ role: "user", content: "Hi" }]
+      }
+    )
+  end
+end
+
+puts "Time with monitoring: #{time.real}s"
+# Overhead is typically < 1ms per request
+```
+
+### Testing
+
+#### Test Environment Setup
+
+```ruby
+# spec/spec_helper.rb or test/test_helper.rb
+if Rails.env.test?
+  Coolhand.configure do |config|
+    config.api_key = 'test_key_do_not_send_requests'
+    config.silent = true
+  end
+end
+```
+
+#### Mocking for Tests
+
+```ruby
+# spec/support/anthropic_mock.rb
+RSpec.configure do |config|
+  config.before(:each) do
+    # Mock Anthropic responses to avoid real API calls
+    allow_any_instance_of(Anthropic::Client).to receive(:messages).and_return(
+      double(
+        content: [double(text: "Mocked response")],
+        model: "claude-3-sonnet-20240229"
+      )
+    )
+  end
+end
+```
+
+## Best Practices
+
+1. **Choose One Gem**: Avoid installing both `anthropic` and `ruby-anthropic` gems
+2. **Secure API Keys**: Use environment variables or Rails credentials, never commit keys
+3. **Silent in Production**: Set `config.silent = true` in production environments
+4. **Monitor Performance**: Use fast models (haiku) for high-frequency requests
+5. **Request Correlation**: Use thread-local request IDs for debugging and feedback
+6. **Streaming Efficiency**: Let Coolhand handle streaming accumulation automatically
+7. **Test Safely**: Mock API responses in test environments to avoid real charges
+
+## API Reference
+
+For complete API documentation, see:
+- [Official Anthropic Gem](https://github.com/anthropics/anthropic-sdk-ruby)
+- [Community Ruby-Anthropic Gem](https://github.com/alexrudall/ruby-anthropic)
+- [Coolhand Feedback API](../README.md#feedback-api)
+
+## Support
+
+- **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