coolhand 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 193fc72a2e4d3c485584250f6f846ba97dbd02f55c357e8bf6f3f95641b669d5
+  data.tar.gz: 4523f4af59e1a81a7763edd5424e86bec7bd35eb40799af7ad253446d9c86bbe
+SHA512:
+  metadata.gz: 6d65bfde6461c4f9676a2e0c64de863204e075abae9b762666119bad7676d21ff962e9aeafb3d0420e86ee9d00e0dcda9e266f99dbfc751b289e5e3c91e028cf
+  data.tar.gz: 48aa86e01741e1a93faec921e65e13a3d434740f91c0c564d22406279d15eab56f60f1aea1bebb5d9c5eb1095200c459b8e728cbd41cc118ee359edfb9eccec1

data/.idea/coolhand-ruby.iml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module version="4">
+  <component name="ModuleRunConfigurationManager">
+    <shared />
+  </component>
+</module>

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,167 @@
+# This is the configuration used to check the rubocop source code.
+
+require:
+  - rubocop-performance
+  - rubocop-rspec
+inherit_gem:
+  test-prof: config/rubocop-rspec.yml
+
+AllCops:
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'spec/fixtures/**/*'
+    - 'tmp/**/*'
+    - '.git/**/*'
+    - 'bin/*'
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+  ActiveSupportExtensionsEnabled: true
+  DocumentationBaseURL: https://docs.rubocop.org/rubocop
+
+# Metrics rules
+Metrics/ModuleLength:
+  CountAsOne: ['array', 'hash', 'heredoc', 'method_call']
+  Max: 200
+
+Metrics/ClassLength:
+  CountAsOne: ['array', 'hash', 'heredoc', 'method_call']
+  Max: 200
+
+Metrics/BlockLength:
+  Max: 50
+  AllowedMethods:
+    - included
+  Exclude:
+    - '**/*.gemspec'
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Metrics/CollectionLiteralLength:
+  LengthThreshold: 500
+
+Metrics/MethodLength:
+  CountAsOne: ['array', 'hash', 'heredoc', 'method_call']
+  Max: 50
+
+# Bundle rules
+Bundler/OrderedGems:
+  Enabled: false
+
+# Style rules
+Style/WordArray:
+  MinSize: 5
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/GuardClause:
+  Enabled: false
+
+Style/SoleNestedConditional:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/InverseMethods:
+  Enabled: false
+
+# Layout rules
+Layout/LineLength:
+  Max: 120
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/ParameterAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/HashAlignment:
+  EnforcedLastArgumentHashStyle: ignore_implicit
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/MultilineAssignmentLayout:
+  EnforcedStyle: same_line
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: variable
+
+Naming/VariableNumber:
+  Enabled: false
+
+# Lint rules
+Lint/EmptyClass:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false
+
+# RSpec rules
+RSpec/HookArgument:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/LetSetup:
+  Enabled: false
+
+RSpec/InstanceVariable:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 6
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+RSpec/DescribedClass:
+  Enabled: false
+
+# Performance rules
+Performance/MethodObjectAsBlock:
+  Enabled: true

data/.simplecov

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+SimpleCov.start do
+  add_filter "/spec/"
+
+  minimum_coverage 70
+end

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2024-10-22
+
+### 🔧 Configuration Improvements
+- **Removed environment variable dependency** - Configuration now only via Ruby config block
+- **Added smart defaults** - Automatically monitors OpenAI and Anthropic APIs by default
+
+### 📚 Documentation
+- **Improved examples** - Added Rails credentials best practices
+- **Clearer configuration** - Removed confusing ENV references
+
+### 🐛 Bug Fixes
+- **Fixed test isolation** - Added configuration reset between tests
+- **Fixed intercept_addresses format** - Corrected to use array instead of string
+
+## [0.1.1] - 2024-10-21
+
+### ✨ New Features
+- **Feedback API Support** - Users can now submit feedback (likes/dislikes, explanations, revised outputs) for LLM responses
+- **Public create_feedback method** - Exposed in FeedbackService for direct feedback submission
+
+### 🏗️ DRYer Architecture
+- **Introduced ApiService base class** - Extracted common API functionality into a shared parent class, reducing code duplication
+- **Renamed Logger to LoggerService** - Better naming consistency and inheritance from ApiService
+- **Added FeedbackService** - New service for submitting LLM request feedback through the API
+
+### 🔧 Development Dependencies
+- **Added webmock gem** - Required for HTTP stubbing in tests
+
+### Changed
+- Updated gem name from "coolhand-ruby" to "coolhand"
+
+## [0.1.0] - 2024-10-21
+
+### Added
+- Initial release of coolhand gem
+- Automatic interception and logging of LLM API calls
+- Net::HTTP patching to capture request and response data
+- Support for Ruby 3.0 and higher

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,327 @@
+# Coolhand Ruby Monitor
+
+Monitor and log LLM API calls from multiple providers (OpenAI, Anthropic, Google AI, Cohere, and more) to the Coolhand analytics platform.
+
+## Installation
+
+```ruby
+gem 'coolhand'
+```
+
+## Getting Started
+
+1. **Get API Key**: Visit [coolhand.io](https://coolhand.io/) to create a free account
+2. **Install**: `gem install coolhand`
+3. **Initialize**: Add configuration to your Ruby application
+4. **Configure**: Set your API key in the configuration block
+5. **Deploy**: Your AI calls are now automatically monitored!
+
+## Quick Start
+
+### Automatic Global Monitoring
+
+🔥 **Set it and forget it! Monitor ALL AI API calls across your entire application with minimal configuration.**
+
+```ruby
+# Add this configuration at the start of your application
+require 'coolhand'
+
+Coolhand.configure do |config|
+  config.api_key = 'your_api_key_here'
+  config.silent = true  # Set to false for debug output
+end
+
+# That's it! ALL AI API calls are now automatically monitored:
+# ✅ OpenAI SDK calls
+# ✅ Anthropic API calls
+# ✅ Direct HTTP requests to AI APIs
+# ✅ ANY library making AI API calls via Faraday
+
+# 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
+- 🔒 **Security built-in** - Automatic credential sanitization
+- ⚡ **Performance optimized** - Negligible overhead via async logging
+- 🛡️ **Future-proof** - Automatically captures new AI calls added by your team
+
+## Feedback API
+
+Collect feedback on LLM responses to improve model performance:
+
+```ruby
+require 'coolhand'
+
+# Create feedback for an LLM response
+feedback_service = Coolhand::Ruby::FeedbackService.new(Coolhand.configuration)
+
+feedback = feedback_service.create_feedback(
+  llm_request_log_id: 123,
+  llm_provider_unique_id: 'req_xxxxxxx',
+  client_unique_id: 'workorder-chat-456',
+  creator_unique_id: 'user-789',
+  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
+)
+```
+
+**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.
+- **`like`** 👍 *Low Signal* - Boolean like/dislike. Lower quality signal but easy for users to provide.
+- **`creator_unique_id`** 👤 *User Tracking* - Unique ID to match feedback to the end user who created it
+
+## Rails Integration
+
+### Configuration
+
+Create an initializer file at `config/initializers/coolhand.rb`:
+
+```ruby
+# config/initializers/coolhand.rb
+Coolhand.configure do |config|
+  # Your Coolhand API Key (Required)
+  # Best practice: Use Rails credentials or environment-specific configuration
+  config.api_key = Rails.application.credentials.coolhand_api_key
+
+  # Set to true to suppress console output
+  config.silent = Rails.env.production?
+
+  # Specify which LLM endpoints to intercept (array of strings)
+  # Optional - defaults to ["api.openai.com", "api.anthropic.com"]
+  # config.intercept_addresses = ["api.openai.com", "api.anthropic.com", "api.cohere.ai"]
+end
+```
+
+### Rails Controller Example
+
+```ruby
+class ChatController < ApplicationController
+  def create_feedback
+    feedback_service = Coolhand::Ruby::FeedbackService.new(Coolhand.configuration)
+
+    feedback = feedback_service.create_feedback(
+      llm_request_log_id: params[:log_id],
+      creator_unique_id: current_user.id,
+      original_output: params[:original_response],
+      revised_output: params[:edited_response],
+      explanation: params[:feedback_text],
+      like: params[:thumbs_up]
+    )
+
+    if feedback
+      render json: { success: true, message: 'Feedback recorded' }
+    else
+      render json: { success: false, message: 'Failed to record feedback' }, status: 422
+    end
+  end
+end
+```
+
+### Background Job Example
+
+```ruby
+class FeedbackCollectionJob < ApplicationJob
+  def perform(feedback_data)
+    feedback_service = Coolhand::Ruby::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]
+    )
+  end
+end
+```
+
+## Configuration Options
+
+### Configuration Parameters
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `api_key` | String | *required* | Your Coolhand API key for authentication |
+| `silent` | Boolean | `false` | Whether to suppress console output |
+| `intercept_addresses` | Array | `["api.openai.com", "api.anthropic.com"]` | Array of API endpoint strings to monitor |
+
+## Usage Examples
+
+### With OpenAI Ruby Client
+
+```ruby
+require 'openai'
+require 'coolhand'
+
+# Configure Coolhand
+Coolhand.configure do |config|
+  config.api_key = 'your_api_key_here'
+end
+
+# Use OpenAI normally - requests are automatically logged
+client = OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
+
+response = client.chat(
+  parameters: {
+    model: "gpt-3.5-turbo",
+    messages: [{ role: "user", content: "These pretzels are making me thirsty!"}],
+    temperature: 0.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'
+
+# 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!
+```
+
+## What Gets Logged
+
+The monitor captures:
+
+- **Request Data**: Method, URL, headers, request body
+- **Response Data**: Status code, headers, response body
+- **Metadata**: Timestamp, protocol used
+- **LLM-Specific**: Model used, token counts, temperature settings
+
+Headers containing API keys are automatically sanitized for security.
+
+## Supported Libraries
+
+The monitor works with any Ruby library that uses Faraday for HTTP(S) requests to LLM APIs, including:
+
+- OpenAI Ruby SDK
+- Anthropic Ruby SDK
+- ruby-openai gem
+- LangChain.rb
+- Direct Faraday requests
+- Any other Faraday-based HTTP client
+
+## How It Works
+
+The gem patches Faraday connections to intercept HTTP requests. When a request matches the 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
+
+For non-matching endpoints, requests pass through unchanged.
+
+## Troubleshooting
+
+### Debugging Output
+
+Enable verbose logging to see what's being intercepted:
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key = 'your_api_key_here'
+  config.silent = false  # Enable console output
+end
+```
+
+### Testing
+
+In test environments, you may want to configure differently:
+
+```ruby
+# config/initializers/coolhand.rb
+if Rails.env.test?
+  Coolhand.configure do |config|
+    config.api_key = 'test_key'
+    config.silent = true
+  end
+end
+```
+
+### Non-Rails Applications
+
+For standard Ruby scripts or non-Rails applications:
+
+```ruby
+#!/usr/bin/env ruby
+require 'coolhand'
+
+Coolhand.configure do |config|
+  config.api_key = 'your_api_key_here'  # Store securely, don't commit to git
+  config.environment = 'production'
+  config.silent = false
+end
+
+# Your application code here...
+```
+
+## API Key
+
+🆓 **Sign up for free** at [coolhand.io](https://coolhand.io/) to get your API key and start monitoring your LLM usage.
+
+**What you get:**
+- Complete LLM request and response logging
+- Usage analytics and insights
+- Feedback collection and quality scoring
+- No credit card required to start
+
+## Error Handling
+
+The monitor handles errors gracefully:
+
+- Failed API logging attempts are logged to console but don't interrupt your application
+- Invalid API keys will be reported but won't crash your app
+- Network issues are handled with appropriate error messages
+
+## Security
+
+- API keys in request headers are automatically redacted
+- No sensitive data is exposed in logs
+- All data is sent via HTTPS to Coolhand servers
+
+## Other Languages
+
+- **Node.js**: [coolhand-node package](https://github.com/coolhand-io/coolhand-node) - Coolhand monitoring for Node.js applications
+- **API Docs**: [API Documentation](https://coolhand.io/docs) - Direct API integration documentation
+
+## Community
+
+- **Questions?** [Create an issue](https://github.com/Coolhand-Labs/coolhand-ruby/issues)
+- **Contribute?** [Submit a pull request](https://github.com/Coolhand-Labs/coolhand-ruby/pulls)
+- **Support?** Visit [coolhandlabs.com](https://coolhandlabs.com)
+
+## License
+
+Apache-2.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/coolhand-ruby.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/coolhand/ruby/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "coolhand"
+  spec.version = Coolhand::Ruby::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.homepage = "https://coolhandlabs.com/"
+  spec.license = "Apache-2.0"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  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"
+
+  # 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.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # 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"
+end

data/lib/coolhand/ruby/api_service.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Coolhand
+  module Ruby
+    class ApiService
+      BASE_URI = "https://coolhand.io/api"
+
+      attr_reader :api_endpoint
+
+      def initialize(endpoint_path)
+        @api_endpoint = "#{BASE_URI}/#{endpoint_path}"
+      end
+
+      def configuration
+        Coolhand.configuration
+      end
+
+      def api_key
+        configuration.api_key
+      end
+
+      def silent
+        configuration.silent
+      end
+
+      protected
+
+      def create_request_options(_payload)
+        {
+          "Content-Type" => "application/json",
+          "X-API-Key" => api_key
+        }
+      end
+
+      def send_request(payload, success_message)
+        uri = URI.parse(@api_endpoint)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        headers = create_request_options(payload)
+        headers.each { |key, value| request[key] = value }
+        request.body = JSON.generate(payload)
+
+        begin
+          response = http.request(request)
+
+          if response.is_a?(Net::HTTPSuccess)
+            result = JSON.parse(response.body, symbolize_names: true)
+            log success_message
+            result
+          else
+            puts "❌ Request failed: #{response.code} - #{response.body}"
+            nil
+          end
+        rescue StandardError => e
+          puts "❌ Request error: #{e.message}"
+          nil
+        end
+      end
+
+      def log(*args)
+        puts args.join(" ") unless silent
+      end
+
+      def log_separator
+        log("═" * 60) unless silent
+      end
+
+      def create_feedback(feedback)
+        payload = {
+          llm_request_log_feedback: feedback
+        }
+
+        log_feedback_info(feedback)
+
+        result = send_request(
+          payload,
+          "✅ Successfully created feedback with ID: #{feedback[:llm_request_log_id] || 'N/A'}"
+        )
+
+        log_separator
+        result
+      end
+
+      def create_log(captured_data)
+        payload = {
+          llm_request_log: {
+            raw_request: captured_data
+          }
+        }
+
+        log_request_info(captured_data)
+
+        result = send_request(
+          payload,
+          "✅ Successfully logged to API"
+        )
+
+        puts "✅ Successfully logged to API with ID: #{result[:id]}" if result && !silent
+
+        log_separator
+        result
+      end
+
+      private
+
+      def log_feedback_info(feedback)
+        return if silent
+
+        puts "\n📝 CREATING FEEDBACK for LLM Request Log ID: #{feedback[:llm_request_log_id]}"
+        puts "👍/👎 Like: #{feedback[:like]}"
+
+        if feedback[:explanation]
+          explanation = feedback[:explanation]
+          truncated = explanation.length > 100 ? "#{explanation[0..99]}..." : explanation
+          puts "💭 Explanation: #{truncated}"
+        end
+
+        puts "📤 Sending to: #{@api_endpoint}"
+      end
+
+      def log_request_info(captured_data)
+        return if silent
+
+        puts "\n🎉 LOGGING OpenAI API Call #{@api_endpoint}"
+        puts captured_data
+        puts "📤 Sending to: #{@api_endpoint}"
+      end
+    end
+  end
+end

data/lib/coolhand/ruby/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Handles all configuration settings for the gem.
+  class Configuration
+    attr_accessor :api_key, :environment, :silent
+    attr_reader :intercept_addresses
+
+    def initialize
+      # Set defaults
+      @environment = "production"
+      @api_key = nil
+      @silent = false
+      @intercept_addresses = ["api.openai.com", "api.anthropic.com"]
+    end
+
+    # Custom setter that preserves defaults when nil/empty array is provided
+    def intercept_addresses=(value)
+      return if value.nil? || (value.is_a?(Array) && value.empty?)
+
+      @intercept_addresses = value.is_a?(Array) ? value : [value]
+    end
+
+    def validate!
+      # Validate API Key after configuration
+      if api_key.nil?
+        Coolhand.log "❌ Coolhand Error: API Key is required. Please set it in the configuration."
+        raise Error, "API Key is required"
+      end
+
+      # Validate intercept_addresses after configuration
+      if intercept_addresses.nil? || intercept_addresses.empty?
+        Coolhand.log "❌ Coolhand Error: Intercept addresses cannot be empty. Please set it in the configuration."
+        raise Error, "Intercept addresses cannot be empty"
+      end
+    end
+  end
+end

data/lib/coolhand/ruby/feedback_service.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "api_service"
+
+module Coolhand
+  module Ruby
+    class FeedbackService < ApiService
+      def initialize
+        super("v2/llm_request_log_feedbacks")
+      end
+
+      public :create_feedback
+    end
+  end
+end

data/lib/coolhand/ruby/interceptor.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Coolhand
+  class Interceptor < Faraday::Middleware
+    ORIGINAL_METHOD_ALIAS = :coolhand_original_initialize
+
+    def self.patch!
+      return if Faraday::Connection.private_method_defined?(ORIGINAL_METHOD_ALIAS)
+
+      Coolhand.log "📡 Monitoring outbound requests ..."
+
+      Faraday::Connection.class_eval do
+        alias_method ORIGINAL_METHOD_ALIAS, :initialize
+
+        def initialize(url = nil, options = nil, &block)
+          send(ORIGINAL_METHOD_ALIAS, url, options, &block)
+
+          use Interceptor
+        end
+      end
+
+      Coolhand.log "🔧 Setting up monitoring for Faraday ..."
+    end
+
+    def self.unpatch!
+      return unless Faraday::Connection.private_method_defined?(ORIGINAL_METHOD_ALIAS)
+
+      Faraday::Connection.class_eval do
+        alias_method :initialize, ORIGINAL_METHOD_ALIAS
+        remove_method ORIGINAL_METHOD_ALIAS
+      end
+
+      Coolhand.log "🔌 Faraday unpatched ..."
+    end
+
+    def call(env)
+      return super unless llm_api_request?(env)
+
+      Coolhand.log "🎯 INTERCEPTING OpenAI call #{env.url}"
+
+      call_data = build_call_data(env)
+      buffer = override_on_data(env)
+
+      process_complete_callback(env, buffer, call_data)
+    end
+
+    private
+
+    def llm_api_request?(env)
+      Coolhand.configuration.intercept_addresses.any? do |address|
+        env.url.to_s.include?(address)
+      end
+    end
+
+    def build_call_data(env)
+      {
+        id: SecureRandom.uuid,
+        timestamp: DateTime.now,
+        method: env.method,
+        url: env.url.to_s,
+        headers: sanitize_headers(env.request_headers),
+        request_body: parse_json(env.request_body),
+        response_body: nil,
+        response_headers: nil,
+        status_code: nil
+      }
+    end
+
+    def override_on_data(env)
+      buffer = +""
+      original_on_data = env.request.on_data
+      env.request.on_data = proc do |chunk, overall_received_bytes|
+        buffer << chunk
+
+        original_on_data&.call(chunk, overall_received_bytes)
+      end
+
+      buffer
+    end
+
+    def process_complete_callback(env, buffer, call_data)
+      @app.call(env).on_complete do |response_env|
+        if buffer.empty?
+          body = response_env.body
+        else
+          body = buffer
+          response_env.body = body
+        end
+
+        call_data[:response_body] = parse_json(body)
+        call_data[:response_headers] = sanitize_headers(response_env.request_headers)
+        call_data[:status_code] = response_env.status
+
+        Thread.new { Coolhand.logger_service.log_to_api(call_data) }
+      end
+    end
+
+    def parse_json(string)
+      JSON.parse(string)
+    rescue JSON::ParserError, TypeError
+      string
+    end
+
+    def sanitize_headers(headers)
+      sanitized = headers.transform_keys(&:to_s).dup
+
+      if sanitized["Authorization"]
+        sanitized["Authorization"] = sanitized["Authorization"].gsub(/Bearer .+/, "Bearer [REDACTED]")
+      end
+
+      %w[openai-api-key api-key].each do |key|
+        sanitized[key] = "[REDACTED]" if sanitized[key]
+      end
+
+      sanitized
+    end
+  end
+end

data/lib/coolhand/ruby/logger_service.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "api_service"
+
+module Coolhand
+  module Ruby
+    class LoggerService < ApiService
+      def initialize
+        super("v2/llm_request_logs")
+      end
+
+      def log_to_api(captured_data)
+        create_log(captured_data)
+      end
+    end
+  end
+end

data/lib/coolhand/ruby/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module Ruby
+    VERSION = "0.1.2"
+  end
+end

data/lib/coolhand/ruby.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "faraday"
+require "securerandom"
+
+require_relative "ruby/version"
+require_relative "ruby/configuration"
+require_relative "ruby/interceptor"
+require_relative "ruby/api_service"
+require_relative "ruby/logger_service"
+require_relative "ruby/feedback_service"
+
+# The main module for the Coolhand gem.
+# It provides the configuration interface and initializes the patching.
+module Coolhand
+  class Error < StandardError; end
+
+  # Class-level instance variables to hold the configuration
+  @configuration = Configuration.new
+
+  class << self
+    attr_reader :configuration
+
+    # Reset configuration to defaults (mainly for testing)
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Provides a block to configure the gem.
+    #
+    # Example:
+    #   Coolhand.configure do |config|
+    #     config.environment = 'development'
+    #     config.silent = false
+    #     config.api_key = "xxx-yyy-zzz"
+    #     config.intercept_addresses = ["openai.com"]
+    #   end
+    def configure
+      yield(configuration)
+
+      configuration.validate!
+
+      # Apply the patch after configuration is set
+      Interceptor.patch!
+
+      log "✅ Coolhand ready - will log OpenAI calls"
+    end
+
+    def capture
+      unless block_given?
+        log "❌ Coolhand Error: Method .capture requires block."
+        return
+      end
+
+      Interceptor.patch!
+
+      yield
+    ensure
+      Interceptor.unpatch!
+    end
+
+    # A simple logger that respects the 'silent' configuration option.
+    def log(message)
+      return if configuration.silent
+
+      puts "COOLHAND: #{message}"
+    end
+
+    # Creates a new FeedbackService instance
+    def feedback_service
+      Ruby::FeedbackService.new
+    end
+
+    # Creates a new LoggerService instance
+    def logger_service
+      Ruby::LoggerService.new
+    end
+  end
+end

data/sig/coolhand/ruby.rbs

@@ -0,0 +1,6 @@
+module Coolhand
+  module Ruby
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: coolhand
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Michael Carroll
+- Yaroslav Malyk
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-22 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby gem to automatically monitor and log external LLM requests. It
+  patches Net::HTTP to capture request and response data.
+email:
+- mc@coolhandlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".idea/coolhand-ruby.iml"
+- ".rspec"
+- ".rubocop.yml"
+- ".simplecov"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- coolhand-ruby.gemspec
+- lib/coolhand/ruby.rb
+- lib/coolhand/ruby/api_service.rb
+- lib/coolhand/ruby/configuration.rb
+- lib/coolhand/ruby/feedback_service.rb
+- lib/coolhand/ruby/interceptor.rb
+- lib/coolhand/ruby/logger_service.rb
+- lib/coolhand/ruby/version.rb
+- sig/coolhand/ruby.rbs
+homepage: https://coolhandlabs.com/
+licenses:
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://coolhandlabs.com/
+  source_code_uri: https://github.com/Coolhand-Labs/coolhand-ruby
+  changelog_uri: https://github.com/Coolhand-Labs/coolhand-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Intercepts and logs OpenAI API calls from a Ruby application.
+test_files: []