payloop 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d134effe2b909cc928b4dfc80149d3c9dcde238be7630bb37dba541fa33be0a
-  data.tar.gz: ddf58b4672381d25ab90b349c6bf29391e4fe099f9e304ba20f5169d3ee6bf1c
+  metadata.gz: 046f4c8d567e9eb4bf8f6797ef0a693f90a279f04de29d9d875030b264323788
+  data.tar.gz: 1fa3b863d95bf6568bb78b0df6819bde803449786ecad95c97c8dde57394689e
 SHA512:
-  metadata.gz: 3b943601582c65f45f66209c6c7aa37c0041f3f961130b3fce5109f09369359d05cc2c7264ca85ffea99b067c95b7c1419d165bf11d847fb994f43a29697c4df
-  data.tar.gz: 2d4ff576bccc13c526dc80ae8ab9b2dfb72a9480f3f6c88ed261a723a217271867a3f6f88e2083f8bb5a65813362b5603e8396bd5a6c944885cbf1c4010fe963
+  metadata.gz: 97cf236a7d99c0cef892e2f8c3d615d47bbba504073d5f64a67b11023859c5ed1ff6ddc67a43b3287ac85ffe37d31e633f1531078ac0ac6ff69f795c30921566
+  data.tar.gz: 205bb28b079d0459021cfb8cd6f1032df7ff7d1c351d9280c4bad530d1fdc73a8e07943d2fc6b36b60bfbcc23df66c1c1c607577e03f6f9fe2af7a7442225291

data/CHANGELOG.md

@@ -35,3 +35,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 - Correct Payloop request payload structure for OpenAI streaming
+
+## [0.1.0] - 2026-02-03
+
+### Added
+- Support for Sentinel intercept.
+- Support for Gemini AI client tracking.

data/lib/payloop/api/sentinel.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Payloop
+  module API
+    class Sentinel < Base
+      def relevance_intercept(payload)
+        post("/sentinel/relevance/intercept", payload)
+      end
+    end
+  end
+end

data/lib/payloop/client.rb

@@ -5,7 +5,7 @@ require "securerandom"
 module Payloop
   # Main Payloop client for tracking AI costs
   class Client
-    attr_reader :config, :collector
+    attr_reader :config, :collector, :sentinel
 
     def initialize(api_key: nil, collector_url: nil, api_url: nil, timeout: nil)
       api_key ||= ENV.fetch("PAYLOOP_API_KEY", nil)
@@ -18,21 +18,32 @@ module Payloop
         timeout: timeout
       )
       @collector = Collector.new(@config)
+      @sentinel = Sentinel.new(@config)
     end
 
     # OpenAI provider wrapper
     def openai
-      @openai ||= Wrappers::OpenAI.new(@config, @collector)
+      @openai ||= Wrappers::OpenAI.new(@config, @collector, @sentinel)
     end
 
     # Anthropic provider wrapper
     def anthropic
-      @anthropic ||= Wrappers::Anthropic.new(@config, @collector)
+      @anthropic ||= Wrappers::Anthropic.new(@config, @collector, @sentinel)
     end
 
-    # Google GenAI provider wrapper
+    # Google GenAI provider wrapper (Tied to google-genai Gem)
+    # This is a port of the official Python library, but it does not
+    # support system prompts which is used for sentinel.  This still
+    # works for non-sentinel use cases.
     def google
-      @google ||= Wrappers::Google.new(@config, @collector)
+      @google ||= Wrappers::Google.new(@config, @collector, @sentinel)
+    end
+
+    # Google GenAI provider wrapper (Tied to gemini-ai Gem version 4.3.0)
+    # Google doesn't have an official Ruby library, so this is seems to be
+    # the most popular unofficial one.
+    def geminiai
+      @geminiai ||= Wrappers::GeminiAI.new(@config, @collector, @sentinel)
     end
 
     # Set attribution for cost tracking

data/lib/payloop/config.rb

@@ -15,6 +15,8 @@ module Payloop
       @version = Payloop::VERSION
       @attribution = Concurrent::AtomicReference.new(nil)
       @tx_uuid = Concurrent::AtomicReference.new(SecureRandom.uuid)
+      @raise_if_irrelevant = Concurrent::AtomicReference.new(false)
+      @secs_irrelevant_request_timeout = Concurrent::AtomicReference.new(5)
     end
 
     def attribution
@@ -33,6 +35,22 @@ module Payloop
       @tx_uuid.set(value)
     end
 
+    def raise_if_irrelevant
+      @raise_if_irrelevant.get
+    end
+
+    def raise_if_irrelevant=(value)
+      @raise_if_irrelevant.set(value)
+    end
+
+    def secs_irrelevant_request_timeout
+      @secs_irrelevant_request_timeout.get
+    end
+
+    def secs_irrelevant_request_timeout=(value)
+      @secs_irrelevant_request_timeout.set(value)
+    end
+
     def new_transaction
       @tx_uuid.set(SecureRandom.uuid)
     end

data/lib/payloop/errors.rb

@@ -27,4 +27,6 @@ module Payloop
       super(message)
     end
   end
+
+  class PayloopRequestInterceptedError < Error; end
 end

data/lib/payloop/sentinel.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Payloop
+  class Sentinel
+    def initialize(config)
+      @config = config
+    end
+
+    def raise_if_irrelevant(enabled: true)
+      raise TypeError, "enabled must be a bool" unless [true, false].include?(enabled)
+
+      @config.raise_if_irrelevant = enabled
+      self
+    end
+
+    def set_secs_irrelevant_request_timeout(timeout)
+      raise TypeError, "timeout must be a Numeric" unless timeout.is_a?(Numeric)
+      raise ArgumentError, "timeout must be greater than 0" unless timeout.positive?
+
+      @config.secs_irrelevant_request_timeout = timeout
+      self
+    end
+
+    def raise_if_irrelevant!(title:, request:, provider: nil, version: nil)
+      return unless @config.raise_if_irrelevant
+
+      begin
+        relevant, reason = make_relevance_intercept_request(
+          title: title,
+          request: request,
+          provider: provider,
+          version: version
+        )
+      rescue StandardError
+        return nil
+      end
+
+      raise PayloopRequestInterceptedError, (reason || "Irrelevant request blocked.") unless relevant
+    end
+
+    private
+
+    def make_relevance_intercept_request(title:, request:, provider: nil, version: nil)
+      payload = {
+        attribution: @config.attribution&.to_h,
+        conversation: {
+          client: {
+            provider: provider,
+            title: title,
+            version: version
+          },
+          request: normalize_request(request)
+        }
+      }
+
+      api = API::Sentinel.new(@config.api_url, @config.api_key, @config.secs_irrelevant_request_timeout)
+      response = api.relevance_intercept(payload) || {}
+
+      relevant = response.key?("relevant") ? response["relevant"] : true
+      reason = relevant ? nil : (response["reason"] || "Irrelevant request blocked.")
+
+      [relevant, reason]
+    end
+
+    def normalize_request(request)
+      # Remove Procs before JSON creation since the
+      # procs or methods will fail for normalization.
+      # We know that OpenAI sends a proc on their
+      # request, so this is mostly for that.
+      cleaned = remove_procs(request)
+      json_obj = JSON.generate(cleaned)
+      JSON.parse(json_obj)
+    rescue StandardError
+      request
+    end
+
+    def remove_procs(obj)
+      case obj
+      when Hash
+        obj.transform_values { |v| remove_procs(v) }
+      when Array
+        obj.map { |v| remove_procs(v) }
+      when Proc, Method
+        true
+      else
+        # Return true object for any callable object; otherwise return obj.
+        obj.respond_to?(:call) || obj
+      end
+    end
+  end
+end

data/lib/payloop/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Payloop
-  VERSION = "0.0.4"
+  VERSION = "0.1.0"
 end

data/lib/payloop/wrappers/anthropic.rb

@@ -6,9 +6,10 @@ module Payloop
   module Wrappers
     # Wrapper for Anthropic Ruby client
     class Anthropic
-      def initialize(config, collector)
+      def initialize(config, collector, sentinel = nil)
         @config = config
         @collector = collector
+        @sentinel = sentinel
       end
 
       def register(client)
@@ -20,6 +21,7 @@ module Payloop
         # Store references in client instance
         client.instance_variable_set(:@payloop_config, @config)
         client.instance_variable_set(:@payloop_collector, @collector)
+        client.instance_variable_set(:@payloop_sentinel, @sentinel)
         client.instance_variable_set(:@payloop_registered, true)
 
         # Wrap the messages method
@@ -43,6 +45,7 @@ module Payloop
         # Store references on the messages resource (needed for Base module)
         messages_resource.instance_variable_set(:@payloop_config, client.instance_variable_get(:@payloop_config))
         messages_resource.instance_variable_set(:@payloop_collector, client.instance_variable_get(:@payloop_collector))
+        messages_resource.instance_variable_set(:@payloop_sentinel, client.instance_variable_get(:@payloop_sentinel))
 
         # Store the original create method
         original_create = messages_resource.method(:create)
@@ -54,6 +57,11 @@ module Payloop
 
           start_time = Time.now
 
+          # Extract parameters for sentinel and analytics
+          params = kwargs.any? ? kwargs : (args.first || {})
+          sentinel = instance_variable_get(:@payloop_sentinel)
+          sentinel&.raise_if_irrelevant!(title: ANTHROPIC_CLIENT_TITLE, request: params)
+
           # Call original method
           response = if kwargs.any?
                        original_create.call(**kwargs, &block)
@@ -61,9 +69,6 @@ module Payloop
                        original_create.call(*args, &block)
                      end
 
-          # Extract parameters for analytics
-          params = kwargs.any? ? kwargs : (args.first || {})
-
           # Submit analytics
           payloop_submit_analytics(
             method: :create,

data/lib/payloop/wrappers/base.rb

@@ -6,7 +6,7 @@ module Payloop
   module Wrappers
     # Base functionality for all provider wrappers
     module Base
-      def payloop_wrap_method(method_name, provider_name)
+      def payloop_wrap_method(method_name, _provider_name)
         return if method(method_name).source_location&.first&.include?("payloop")
 
         original_method = instance_method(method_name)
@@ -43,7 +43,8 @@ module Payloop
         end
       end
 
-      def payloop_submit_analytics(method:, args:, kwargs:, response:, start_time:, end_time:, provider: nil, title: nil)
+      def payloop_submit_analytics(method:, args:, kwargs:, response:, start_time:,
+                                   end_time:, provider: nil, title: nil)
         collector = instance_variable_get(:@payloop_collector)
         config = instance_variable_get(:@payloop_config)
 
@@ -63,7 +64,8 @@ module Payloop
         collector.submit_async(payload)
       end
 
-      def payloop_submit_error_analytics(method:, args:, kwargs:, error:, start_time:, end_time:, provider: nil, title: nil)
+      def payloop_submit_error_analytics(method:, args:, kwargs:, error:, start_time:,
+                                         end_time:, provider: nil, title: nil)
         collector = instance_variable_get(:@payloop_collector)
         config = instance_variable_get(:@payloop_config)
 
@@ -135,9 +137,7 @@ module Payloop
 
         # Normalize stream parameter: convert Proc to boolean true
         # This ensures streaming requests are properly serialized to JSON
-        if query.is_a?(Hash) && query[:stream].is_a?(Proc)
-          query[:stream] = true
-        end
+        query[:stream] = true if query.is_a?(Hash) && query[:stream].is_a?(Proc)
 
         query
       rescue StandardError
@@ -146,7 +146,7 @@ module Payloop
 
       def extract_response(response)
         case response
-        when Hash
+        when Hash, Array
           deep_copy(response)
         when String
           { text: response }
@@ -206,7 +206,16 @@ module Payloop
         end
       end
 
-      def build_payload(query:, response:, start_time:, end_time:, config:, status:, provider: nil, title: nil, exception: nil)
+      # Build the payload that is sent to the collector API which then sends the payload
+      # to the backend.
+      # - conversion.client - Routes the payload to the correct service
+      # in the backend.  So, the title and provider values are known values.  (e.g google,
+      # openai, and anthropic) are common title values.
+      # - conversion.query - Holds the request information.
+      # - conversion.response - Holds the response from the LLM.  This is different for each LLM,
+      # and the different services handle them on the backend.
+      def build_payload(query:, response:, start_time:, end_time:, config:, status:,
+                        provider: nil, title: nil, exception: nil)
         {
           attribution: config.attribution&.to_h,
           conversation: {

data/lib/payloop/wrappers/geminiai.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Payloop
+  module Wrappers
+    # Wrapper for Google GenerativeAI Ruby client (gemini-ai gem version 4.3.0)
+    class GeminiAI
+      def initialize(config, collector, sentinel = nil)
+        @config = config
+        @collector = collector
+        @sentinel = sentinel
+      end
+
+      def register(client)
+        validate_client!(client)
+
+        # Prevent double registration
+        return client if client.instance_variable_defined?(:@payloop_registered)
+
+        # Store references in client instance
+        client.instance_variable_set(:@payloop_config, @config)
+        client.instance_variable_set(:@payloop_collector, @collector)
+        client.instance_variable_set(:@payloop_sentinel, @sentinel)
+        client.instance_variable_set(:@payloop_registered, true)
+
+        # Wrap the generate_content and stream_generate_content methods
+        wrap_generate_content_method(client)
+        wrap_stream_generate_content_method(client)
+
+        client
+      end
+
+      private
+
+      def validate_client!(client)
+        return if client.respond_to?(:generate_content) && client.respond_to?(:stream_generate_content)
+
+        raise RegistrationError,
+              "Client does not appear to be a valid Gemini AI client (missing generate_content or stream_generate_content method)" # rubocop:disable Layout/LineLength
+      end
+
+      def wrap_generate_content_method(client)
+        client.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_generate_content, :generate_content
+
+          define_method(:generate_content) do |*args, **kwargs, &block|
+            # Handle both positional hash and keyword arguments
+            parameters = if args.first.is_a?(Hash)
+                           args.first
+                         elsif kwargs.any?
+                           kwargs
+                         else
+                           {}
+                         end
+
+            start_time = Time.now
+
+            sentinel = instance_variable_get(:@payloop_sentinel)
+            sentinel&.raise_if_irrelevant!(title: GOOGLE_CLIENT_TITLE, request: parameters)
+
+            # Call original method
+            response = original_generate_content(*args, **kwargs, &block)
+
+            # Submit analytics
+            payloop_submit_analytics(
+              method: :generate_content,
+              args: [],
+              kwargs: parameters,
+              response: response,
+              start_time: start_time,
+              end_time: Time.now,
+              title: GOOGLE_CLIENT_TITLE
+            )
+
+            response
+          rescue StandardError => e
+            payloop_submit_error_analytics(
+              method: :generate_content,
+              args: [],
+              kwargs: parameters,
+              error: e,
+              start_time: start_time,
+              end_time: Time.now,
+              title: GOOGLE_CLIENT_TITLE
+            )
+
+            raise e
+          end
+        end
+      end
+
+      # Handles the stream_generate_content from the client.  Note, that
+      # the Payloop backend does not expect the payload to be merged like
+      # the OpenAI payload is.  So, all the results are just sent as an
+      # array.
+      def wrap_stream_generate_content_method(client)
+        client.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_stream_generate_content, :stream_generate_content
+
+          define_method(:stream_generate_content) do |*args, **kwargs, &block|
+            # Handle both positional hash and keyword arguments
+            parameters = if args.first.is_a?(Hash)
+                           args.first
+                         elsif kwargs.any?
+                           kwargs
+                         else
+                           {}
+                         end
+
+            start_time = Time.now
+
+            sentinel = instance_variable_get(:@payloop_sentinel)
+            sentinel&.raise_if_irrelevant!(title: GOOGLE_CLIENT_TITLE, request: parameters)
+
+            # Call original method with wrapped block
+            response = original_stream_generate_content(*args, **kwargs, &block)
+
+            # Submit analytics with accumulated response
+            payloop_submit_analytics(
+              method: :stream_generate_content,
+              args: [],
+              kwargs: parameters,
+              response: response,
+              start_time: start_time,
+              end_time: Time.now,
+              title: GOOGLE_CLIENT_TITLE
+            )
+
+            response
+          rescue StandardError => e
+            payloop_submit_error_analytics(
+              method: :stream_generate_content,
+              args: [],
+              kwargs: parameters,
+              error: e,
+              start_time: start_time,
+              end_time: Time.now,
+              title: GOOGLE_CLIENT_TITLE
+            )
+
+            raise e
+          end
+        end
+      end
+    end
+  end
+end

data/lib/payloop/wrappers/google.rb

@@ -4,11 +4,12 @@ require_relative "constants"
 
 module Payloop
   module Wrappers
-    # Wrapper for Google GenerativeAI Ruby client (google-genai gem)
+    # Wrapper for Google GenerativeAI Ruby client (google-genai library version 0.1)
     class Google
-      def initialize(config, collector)
+      def initialize(config, collector, sentinel = nil)
         @config = config
         @collector = collector
+        @sentinel = sentinel
       end
 
       def register(client)
@@ -23,6 +24,7 @@ module Payloop
         # Store references in client instance
         client.instance_variable_set(:@payloop_config, @config)
         client.instance_variable_set(:@payloop_collector, @collector)
+        client.instance_variable_set(:@payloop_sentinel, @sentinel)
         client.instance_variable_set(:@payloop_registered, true)
 
         # Wrap the generate_content method
@@ -61,6 +63,7 @@ module Payloop
         # Store references on the models resource (needed for Base module)
         models_resource.instance_variable_set(:@payloop_config, client.instance_variable_get(:@payloop_config))
         models_resource.instance_variable_set(:@payloop_collector, client.instance_variable_get(:@payloop_collector))
+        models_resource.instance_variable_set(:@payloop_sentinel, client.instance_variable_get(:@payloop_sentinel))
 
         # Store the original generate_content method
         original_generate_content = models_resource.method(:generate_content)
@@ -72,6 +75,12 @@ module Payloop
 
           start_time = Time.now
 
+          # Extract parameters for analytics
+          params = kwargs.any? ? kwargs : (args.first || {})
+
+          sentinel = instance_variable_get(:@payloop_sentinel)
+          sentinel&.raise_if_irrelevant!(title: GOOGLE_CLIENT_TITLE, request: params)
+
           # Call original method
           response = if kwargs.any?
                        original_generate_content.call(**kwargs, &block)
@@ -79,9 +88,6 @@ module Payloop
                        original_generate_content.call(*args, &block)
                      end
 
-          # Extract parameters for analytics
-          params = kwargs.any? ? kwargs : (args.first || {})
-
           # Submit analytics
           payloop_submit_analytics(
             method: :generate_content,

data/lib/payloop/wrappers/openai.rb

@@ -6,9 +6,10 @@ module Payloop
   module Wrappers
     # Wrapper for OpenAI Ruby client (ruby-openai gem)
     class OpenAI
-      def initialize(config, collector)
+      def initialize(config, collector, sentinel = nil)
         @config = config
         @collector = collector
+        @sentinel = sentinel
       end
 
       def register(client)
@@ -20,6 +21,7 @@ module Payloop
         # Store references in client instance
         client.instance_variable_set(:@payloop_config, @config)
         client.instance_variable_set(:@payloop_collector, @collector)
+        client.instance_variable_set(:@payloop_sentinel, @sentinel)
         client.instance_variable_set(:@payloop_registered, true)
 
         # Wrap the chat method
@@ -45,6 +47,9 @@ module Payloop
           define_method(:chat) do |parameters: {}|
             start_time = Time.now
 
+            sentinel = instance_variable_get(:@payloop_sentinel)
+            sentinel&.raise_if_irrelevant!(title: OPENAI_CLIENT_TITLE, request: parameters)
+
             # Detect streaming and wrap callback to accumulate chunks
             streaming = parameters[:stream].is_a?(Proc)
             accumulated_response = {} if streaming

data/lib/payloop.rb

@@ -3,13 +3,16 @@
 require_relative "payloop/version"
 require_relative "payloop/errors"
 require_relative "payloop/config"
+require_relative "payloop/sentinel"
 require_relative "payloop/attribution"
 require_relative "payloop/collector"
 require_relative "payloop/wrappers/base"
 require_relative "payloop/wrappers/openai"
 require_relative "payloop/wrappers/anthropic"
 require_relative "payloop/wrappers/google"
+require_relative "payloop/wrappers/geminiai"
 require_relative "payloop/api/base"
+require_relative "payloop/api/sentinel"
 require_relative "payloop/api/workflows"
 require_relative "payloop/api/invocation"
 require_relative "payloop/api/workflow"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: payloop
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - Payloop
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-29 00:00:00.000000000 Z
+date: 2026-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -37,6 +37,7 @@ files:
 - lib/payloop.rb
 - lib/payloop/api/base.rb
 - lib/payloop/api/invocation.rb
+- lib/payloop/api/sentinel.rb
 - lib/payloop/api/workflow.rb
 - lib/payloop/api/workflows.rb
 - lib/payloop/attribution.rb
@@ -44,10 +45,12 @@ files:
 - lib/payloop/collector.rb
 - lib/payloop/config.rb
 - lib/payloop/errors.rb
+- lib/payloop/sentinel.rb
 - lib/payloop/version.rb
 - lib/payloop/wrappers/anthropic.rb
 - lib/payloop/wrappers/base.rb
 - lib/payloop/wrappers/constants.rb
+- lib/payloop/wrappers/geminiai.rb
 - lib/payloop/wrappers/google.rb
 - lib/payloop/wrappers/openai.rb
 homepage: https://trypayloop.com