payloop 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8afd4c12089fbda44abae722ada80ee75413b18d043aa7c8b5ab23b4c77e15c8
+  data.tar.gz: 7b9b9bc476434ef3c4b83dde77cde3ec0a506627324b1275decbdce16ba5ee42
+SHA512:
+  metadata.gz: a07580586b5a649a60c6eb1dd7823de6f33af0243379b11517225db7546b8b87cd8ad3bea690ce626628d3117f78aecc2faf46dbf3e3a51378234d2045409d28
+  data.tar.gz: ca34c48b13d65ac23d9b65a0217bc66d0b0e7b548c6395c7f3f2e9da805d4d242c3f9590b2f0650639d2cacf74144368f951e74bd1af98a4eb35f3146a0da165

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 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.0.1] - 2025-10-13
+
+### Added
+- Initial release of Payloop Ruby SDK
+- Support for OpenAI client tracking
+- Support for Anthropic client tracking
+- Support for Google GenAI client tracking
+- Attribution tracking (parent/subsidiary hierarchy)
+- Transaction management
+- Asynchronous analytics collection
+- Workflow API client
+- Invocation API client
+- Streaming response support
+- Thread-safe configuration
+- Comprehensive error handling

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PayloopAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,29 @@
+# Welcome to Payloop!
+
+### Cost Visibility for AI Agents
+
+Payloop is a lightweight infrastructure layer that gives AI teams real-time visibility into the true costs of deploying agents - across tasks, workflows, and customers. Most teams today can’t see what it actually costs to deploy their agents, making it nearly impossible to manage gross margins or price with confidence.
+
+With just a single line of code, Payloop delivers:
+- Cost tracking across OpenAI, Anthropic, Gemini, and more in one place
+- Breakdowns by task, agent, and customer in real time
+- Confidence to deploy the right pricing model (cost-plus, token-based, outcome-based, etc.) while preserving gross margins
+
+Watch a short demo video: [Payloop Walkthrough Video](https://www.youtube.com/watch?v=Z-GkSl_7imY)
+
+By surfacing exactly what’s driving cost and value, Payloop becomes the source of truth for agent economics - helping founders and operators scale their agents with confidence.
+
+Sign up here: [trypayloop.com](https://trypayloop.com/)
+
+# Installation
+
+    gem install payloop
+
+# Documentation
+
+Our SDK reference provides documentation for:
+- Understanding how Payloop works
+- Demonstrating how to integrate Payloop into your product
+- Code samples to illustrate our SDK and API
+
+Check it out here: [developers.trypayloop.com](https://developers.trypayloop.com)

data/lib/payloop/api/base.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Payloop
+  module API
+    # Base HTTP client for Payloop API
+    class Base
+      def initialize(api_url, api_key, timeout)
+        @original_api_url = api_url
+        @api_url = "#{api_url}/v1/-"
+        @api_key = api_key
+        @timeout = timeout
+      end
+
+      protected
+
+      def get(path)
+        request(:get, path)
+      end
+
+      def post(path, body = nil)
+        request(:post, path, body)
+      end
+
+      def put(path, body = nil)
+        request(:put, path, body)
+      end
+
+      def delete(path)
+        request(:delete, path)
+      end
+
+      private
+
+      def request(method, path, body = nil)
+        # Construct full URL - path should start with /
+        full_url = "#{@api_url}#{path}"
+        uri = URI.parse(full_url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+
+        # Configure SSL to use system certificates
+        if http.use_ssl?
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.cert_store = OpenSSL::X509::Store.new
+          http.cert_store.set_default_paths
+        end
+
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        request = build_request(method, uri, body)
+        response = http.request(request)
+
+        handle_response(response)
+      end
+
+      def build_request(method, uri, body)
+        request_class = case method
+                        when :get then Net::HTTP::Get
+                        when :post then Net::HTTP::Post
+                        when :put then Net::HTTP::Put
+                        when :delete then Net::HTTP::Delete
+                        else raise ArgumentError, "Unsupported HTTP method: #{method}"
+                        end
+
+        request = request_class.new(uri.path.empty? ? "/" : uri.path)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request["User-Agent"] = "payloop-ruby/#{Payloop::VERSION}"
+
+        request.body = JSON.generate(body) if body && %i[post put].include?(method)
+
+        request
+      end
+
+      def handle_response(response)
+        case response
+        when Net::HTTPSuccess
+          parse_json_response(response.body)
+        when Net::HTTPNoContent
+          {}
+        else
+          raise APIError.new(
+            "API request failed: #{response.code} #{response.message}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        end
+      end
+
+      def parse_json_response(body)
+        return {} if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise APIError, "Failed to parse JSON response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/payloop/api/invocation.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Payloop
+  module API
+    # API client for workflow invocation operations
+    class Invocation < Base
+      def initialize(api_url, api_key, timeout)
+        super(api_url, api_key, timeout)
+        @attribution = nil
+      end
+
+      # Set attribution filter for summary queries
+      # Returns self for method chaining
+      def attribution(parent_id:, parent_name: nil, subsidiary_id: nil, subsidiary_name: nil)
+        @attribution = {
+          parent: { id: parent_id }
+        }
+        @attribution[:parent][:name] = parent_name if parent_name
+
+        if subsidiary_id
+          @attribution[:subsidiary] = { id: subsidiary_id }
+          @attribution[:subsidiary][:name] = subsidiary_name if subsidiary_name
+        end
+
+        self
+      end
+
+      # Get invocation summary for a workflow
+      def summary(workflow_uuid, date_start:, date_end: nil)
+        body = {
+          date: {
+            start: format_date(date_start)
+          }
+        }
+
+        if date_end
+          body[:date][:end] = format_date(date_end)
+        end
+
+        body[:attribution] = @attribution if @attribution
+
+        post("/workflow/#{workflow_uuid}/invocation/summary", body)
+      end
+
+      private
+
+      def format_date(date)
+        return date if date.is_a?(String)
+
+        # Convert to midnight (beginning of day) in ISO8601 format
+        if date.respond_to?(:to_date)
+          date.to_date.to_time.iso8601
+        else
+          date.iso8601
+        end
+      end
+    end
+  end
+end

data/lib/payloop/api/workflow.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Payloop
+  module API
+    # API client for managing a specific workflow
+    class Workflow < Base
+      def initialize(uuid, api_url, api_key, timeout)
+        super(api_url, api_key, timeout)
+        @uuid = uuid
+      end
+
+      # Get workflow details
+      def details
+        get("/workflow/#{@uuid}")
+      end
+
+      # Update workflow label
+      def update(label:)
+        body = { label: label }
+        put("/workflow/#{@uuid}", body)
+      end
+
+      # Delete workflow
+      def destroy
+        delete("/workflow/#{@uuid}")
+      end
+
+      # Get invocation client for this workflow
+      def invocation
+        Invocation.new(@uuid, @original_api_url, @api_key, @timeout)
+      end
+    end
+  end
+end

data/lib/payloop/api/workflows.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Payloop
+  module API
+    # API client for managing workflows
+    class Workflows < Base
+      # List all workflows
+      def list
+        get("/workflows")
+      end
+
+      # Create a new workflow
+      def create(name:, description: nil)
+        post("/workflows", { name: name, description: description }.compact)
+      end
+
+      # Get workflow details
+      def details(uuid)
+        get("/workflow/#{uuid}")
+      end
+
+      # Update workflow label
+      def update(uuid, label:)
+        body = { label: label }
+        put("/workflow/#{uuid}", body)
+      end
+
+      # Delete workflow
+      def destroy(uuid)
+        delete("/workflow/#{uuid}")
+      end
+
+      # Get invocation manager for workflow operations
+      def invocation
+        @invocation ||= Invocation.new(@original_api_url, @api_key, @timeout)
+      end
+    end
+  end
+end

data/lib/payloop/attribution.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Payloop
+  # Attribution tracks cost hierarchy for API calls
+  class Attribution
+    attr_reader :parent_id, :parent_name, :subsidiary_id, :subsidiary_name
+
+    def initialize(parent_id:, parent_name: nil, subsidiary_id: nil, subsidiary_name: nil)
+      @parent_id = validate_parent_id!(parent_id)
+      @parent_name = validate_string_length!(parent_name, "parent_name") if parent_name
+      @subsidiary_id = validate_string_length!(subsidiary_id, "subsidiary_id") if subsidiary_id
+      @subsidiary_name = validate_string_length!(subsidiary_name, "subsidiary_name") if subsidiary_name
+
+      validate_subsidiary_requirements!
+    end
+
+    def to_h
+      result = {
+        parent: {
+          id: parent_id
+        }
+      }
+
+      result[:parent][:name] = parent_name if parent_name
+
+      if subsidiary_id
+        result[:subsidiary] = { id: subsidiary_id }
+        result[:subsidiary][:name] = subsidiary_name if subsidiary_name
+      end
+
+      result
+    end
+
+    private
+
+    def validate_parent_id!(value)
+      raise ValidationError, "parent_id is required" if value.nil? || value.to_s.empty?
+
+      value_str = value.to_s
+      if value_str.length > 100
+        raise ValidationError, "parent_id cannot exceed 100 characters (got #{value_str.length})"
+      end
+
+      value_str
+    end
+
+    def validate_string_length!(value, field_name)
+      return nil if value.nil?
+
+      value_str = value.to_s
+      if value_str.length > 100
+        raise ValidationError, "#{field_name} cannot exceed 100 characters (got #{value_str.length})"
+      end
+
+      value_str
+    end
+
+    def validate_subsidiary_requirements!
+      return unless subsidiary_name && !subsidiary_id
+
+      raise ValidationError, "subsidiary_id is required when subsidiary_name is provided"
+    end
+  end
+end

data/lib/payloop/client.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Payloop
+  # Main Payloop client for tracking AI costs
+  class Client
+    attr_reader :config, :collector
+
+    def initialize(api_key: nil, collector_url: nil, api_url: nil, timeout: nil)
+      api_key ||= ENV.fetch("PAYLOOP_API_KEY", nil)
+      raise MissingAPIKeyError if api_key.nil? || api_key.empty?
+
+      @config = Config.new(
+        api_key: api_key,
+        collector_url: collector_url,
+        api_url: api_url,
+        timeout: timeout
+      )
+      @collector = Collector.new(@config)
+    end
+
+    # OpenAI provider wrapper
+    def openai
+      @openai ||= Wrappers::OpenAI.new(@config, @collector)
+    end
+
+    # Anthropic provider wrapper
+    def anthropic
+      @anthropic ||= Wrappers::Anthropic.new(@config, @collector)
+    end
+
+    # Google GenAI provider wrapper
+    def google
+      @google ||= Wrappers::Google.new(@config, @collector)
+    end
+
+    # Set attribution for cost tracking
+    def attribution(parent_id:, parent_name: nil, subsidiary_id: nil, subsidiary_name: nil,
+                    parent_uuid: nil, subsidiary_uuid: nil)
+      # Support deprecated parameters
+      parent_id ||= parent_uuid
+      subsidiary_id ||= subsidiary_uuid
+
+      attr = Attribution.new(
+        parent_id: parent_id,
+        parent_name: parent_name,
+        subsidiary_id: subsidiary_id,
+        subsidiary_name: subsidiary_name
+      )
+
+      @config.attribution = attr
+      self
+    end
+
+    # Start a new transaction
+    def new_transaction
+      @config.new_transaction
+      self
+    end
+
+    # Get workflows API client
+    def workflows
+      @workflows ||= API::Workflows.new(
+        @config.api_url,
+        @config.api_key,
+        @config.timeout
+      )
+    end
+
+    # Gracefully shutdown the client
+    def shutdown
+      @collector.shutdown
+    end
+  end
+end

data/lib/payloop/collector.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "concurrent"
+
+module Payloop
+  # Handles asynchronous submission of analytics to Payloop collector
+  class Collector
+    DEFAULT_MAX_RETRIES = 3
+    RETRY_DELAY = 1 # seconds
+
+    def initialize(config)
+      @config = config
+      @executor = Concurrent::ThreadPoolExecutor.new(
+        min_threads: 1,
+        max_threads: 5,
+        max_queue: 100,
+        fallback_policy: :discard
+      )
+    end
+
+    # Submit analytics payload asynchronously
+    def submit_async(payload)
+      @executor.post do
+        submit_with_retry(payload)
+      rescue StandardError => e
+        warn "Payloop: Failed to submit analytics: #{e.message}"
+      end
+    end
+
+    # Submit analytics payload synchronously (for testing)
+    def submit(payload)
+      submit_with_retry(payload)
+    end
+
+    # Gracefully shutdown the collector
+    def shutdown
+      @executor.shutdown
+      @executor.wait_for_termination(5)
+    end
+
+    private
+
+    def submit_with_retry(payload, attempt = 1)
+      response = post_to_collector(payload)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise APIError.new(
+          "Collector request failed: #{response.code} #{response.message}",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      end
+
+      response
+    rescue StandardError => e
+      raise e unless attempt < DEFAULT_MAX_RETRIES
+
+      sleep(RETRY_DELAY * attempt)
+      submit_with_retry(payload, attempt + 1)
+    end
+
+    def post_to_collector(payload)
+      uri = URI.parse(@config.collector_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      # Configure SSL to use system certificates
+      if http.use_ssl?
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.cert_store = OpenSSL::X509::Store.new
+        http.cert_store.set_default_paths
+      end
+
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
+
+      request = Net::HTTP::Post.new("/rec")
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "payloop-ruby/#{@config.version}"
+      request.body = JSON.generate(payload)
+
+      http.request(request)
+    end
+  end
+end

data/lib/payloop/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Payloop
+  # Thread-safe configuration for Payloop client
+  class Config
+    attr_reader :api_key, :collector_url, :api_url, :timeout, :version
+
+    def initialize(api_key: nil, collector_url: nil, api_url: nil, timeout: nil)
+      @api_key = api_key
+      @collector_url = collector_url || "https://collector.trypayloop.com"
+      @api_url = api_url || "https://api.trypayloop.com"
+      @timeout = timeout || 5
+      @version = Payloop::VERSION
+      @attribution = Concurrent::AtomicReference.new(nil)
+      @tx_uuid = Concurrent::AtomicReference.new(SecureRandom.uuid)
+    end
+
+    def attribution
+      @attribution.get
+    end
+
+    def attribution=(value)
+      @attribution.set(value)
+    end
+
+    def tx_uuid
+      @tx_uuid.get
+    end
+
+    def tx_uuid=(value)
+      @tx_uuid.set(value)
+    end
+
+    def new_transaction
+      @tx_uuid.set(SecureRandom.uuid)
+    end
+  end
+end

data/lib/payloop/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Payloop
+  # Base error class for all Payloop errors
+  class Error < StandardError; end
+
+  # Raised when API key is missing
+  class MissingAPIKeyError < Error
+    def initialize(msg = "API key is missing. Set PAYLOOP_API_KEY environment variable or pass api_key parameter.")
+      super
+    end
+  end
+
+  # Raised when validation fails
+  class ValidationError < Error; end
+
+  # Raised when client registration fails
+  class RegistrationError < Error; end
+
+  # Raised when API request fails
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+end

data/lib/payloop/version.rb

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

data/lib/payloop/wrappers/anthropic.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Payloop
+  module Wrappers
+    # Wrapper for Anthropic Ruby client
+    class Anthropic
+      def initialize(config, collector)
+        @config = config
+        @collector = collector
+      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_registered, true)
+
+        # Wrap the messages method
+        wrap_messages_method(client)
+
+        client
+      end
+
+      private
+
+      def validate_client!(client)
+        return if client.respond_to?(:messages)
+
+        raise RegistrationError, "Client does not appear to be a valid Anthropic client (missing messages method)"
+      end
+
+      def wrap_messages_method(client)
+        # Get the messages resource
+        messages_resource = client.messages
+
+        # 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))
+
+        # Store the original create method
+        original_create = messages_resource.method(:create)
+
+        # Wrap the create method
+        messages_resource.define_singleton_method(:create) do |*args, **kwargs, &block|
+          # Include Base module methods
+          extend Base unless singleton_class.include?(Base)
+
+          start_time = Time.now
+
+          # Call original method
+          response = if kwargs.any?
+                       original_create.call(**kwargs, &block)
+                     else
+                       original_create.call(*args, &block)
+                     end
+
+          # Extract parameters for analytics
+          params = kwargs.any? ? kwargs : (args.first || {})
+
+          # Submit analytics
+          payloop_submit_analytics(
+            provider: "anthropic",
+            method: :create,
+            args: args,
+            kwargs: params,
+            response: response,
+            start_time: start_time,
+            end_time: Time.now
+          )
+
+          response
+        rescue StandardError => e
+          params = kwargs.any? ? kwargs : (args.first || {})
+
+          payloop_submit_error_analytics(
+            provider: "anthropic",
+            method: :create,
+            args: args,
+            kwargs: params,
+            error: e,
+            start_time: start_time,
+            end_time: Time.now
+          )
+
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/payloop/wrappers/base.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Payloop
+  module Wrappers
+    # Base functionality for all provider wrappers
+    module Base
+      def payloop_wrap_method(method_name, provider_name)
+        return if method(method_name).source_location&.first&.include?("payloop")
+
+        original_method = instance_method(method_name)
+
+        define_method(method_name) do |*args, **kwargs, &block|
+          start_time = Time.now
+
+          # Call original method
+          response = original_method.bind(self).call(*args, **kwargs, &block)
+
+          # Submit analytics asynchronously
+          payloop_submit_analytics(
+            provider: provider_name,
+            method: method_name,
+            args: args,
+            kwargs: kwargs,
+            response: response,
+            start_time: start_time,
+            end_time: Time.now
+          )
+
+          response
+        rescue StandardError => e
+          # Submit error analytics
+          payloop_submit_error_analytics(
+            provider: provider_name,
+            method: method_name,
+            args: args,
+            kwargs: kwargs,
+            error: e,
+            start_time: start_time,
+            end_time: Time.now
+          )
+
+          raise e
+        end
+      end
+
+      def payloop_submit_analytics(provider:, method:, args:, kwargs:, response:, start_time:, end_time:)
+        collector = instance_variable_get(:@payloop_collector)
+        config = instance_variable_get(:@payloop_config)
+
+        return unless collector && config
+
+        payload = build_payload(
+          provider: provider,
+          query: extract_query(method, args, kwargs),
+          response: extract_response(response),
+          start_time: start_time,
+          end_time: end_time,
+          config: config,
+          status: "succeeded"
+        )
+
+        collector.submit_async(payload)
+      end
+
+      def payloop_submit_error_analytics(provider:, method:, args:, kwargs:, error:, start_time:, end_time:)
+        collector = instance_variable_get(:@payloop_collector)
+        config = instance_variable_get(:@payloop_config)
+
+        return unless collector && config
+
+        payload = build_payload(
+          provider: provider,
+          query: extract_query(method, args, kwargs),
+          response: { error: error.message, class: error.class.name },
+          start_time: start_time,
+          end_time: end_time,
+          config: config,
+          status: "failed",
+          exception: error.message
+        )
+
+        collector.submit_async(payload)
+      end
+
+      private
+
+      def extract_query(_method, _args, kwargs)
+        # Deep copy to avoid mutation issues
+        deep_copy(kwargs)
+      rescue StandardError
+        {}
+      end
+
+      def extract_response(response)
+        case response
+        when Hash
+          deep_copy(response)
+        when String
+          { text: response }
+        else
+          if response.respond_to?(:to_h)
+            deep_copy(response.to_h)
+          elsif response.respond_to?(:to_hash)
+            deep_copy(response.to_hash)
+          else
+            { raw: response.to_s }
+          end
+        end
+      rescue StandardError
+        { raw: response.to_s }
+      end
+
+      def deep_copy(obj)
+        Marshal.load(Marshal.dump(obj))
+      rescue StandardError
+        begin
+          obj.dup
+        rescue StandardError
+          obj
+        end
+      end
+
+      def build_payload(provider:, query:, response:, start_time:, end_time:, config:, status:, exception: nil)
+        {
+          attribution: config.attribution&.to_h,
+          conversation: {
+            client: {
+              provider: provider,
+              title: provider,
+              version: nil
+            },
+            query: query,
+            response: response
+          },
+          meta: {
+            api: {
+              key: config.api_key
+            },
+            fnfg: {
+              status: status,
+              exc: exception
+            },
+            sdk: {
+              client: "ruby",
+              version: config.version
+            }
+          },
+          time: {
+            start: start_time.iso8601(3),
+            end: end_time.iso8601(3)
+          },
+          tx: {
+            uuid: config.tx_uuid
+          }
+        }
+      end
+    end
+  end
+end

data/lib/payloop/wrappers/google.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Payloop
+  module Wrappers
+    # Wrapper for Google GenerativeAI Ruby client
+    class Google
+      def initialize(config, collector)
+        @config = config
+        @collector = collector
+      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_registered, true)
+
+        # Wrap the generate_content method
+        wrap_generate_content_method(client)
+
+        client
+      end
+
+      private
+
+      def validate_client!(client)
+        return if client.respond_to?(:models)
+
+        raise RegistrationError,
+              "Client does not appear to be a valid Google GenAI client (missing models method)"
+      end
+
+      def wrap_generate_content_method(client)
+        # Get the models resource
+        models_resource = client.models
+
+        # 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))
+
+        # Store the original generate_content method
+        original_generate_content = models_resource.method(:generate_content)
+
+        # Wrap the generate_content method
+        models_resource.define_singleton_method(:generate_content) do |*args, **kwargs, &block|
+          # Include Base module methods
+          extend Base unless singleton_class.include?(Base)
+
+          start_time = Time.now
+
+          # Call original method
+          response = if kwargs.any?
+                       original_generate_content.call(**kwargs, &block)
+                     else
+                       original_generate_content.call(*args, &block)
+                     end
+
+          # Extract parameters for analytics
+          params = kwargs.any? ? kwargs : (args.first || {})
+
+          # Submit analytics
+          payloop_submit_analytics(
+            provider: "google",
+            method: :generate_content,
+            args: args,
+            kwargs: params,
+            response: response,
+            start_time: start_time,
+            end_time: Time.now
+          )
+
+          response
+        rescue StandardError => e
+          params = kwargs.any? ? kwargs : (args.first || {})
+
+          payloop_submit_error_analytics(
+            provider: "google",
+            method: :generate_content,
+            args: args,
+            kwargs: params,
+            error: e,
+            start_time: start_time,
+            end_time: Time.now
+          )
+
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/payloop/wrappers/openai.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Payloop
+  module Wrappers
+    # Wrapper for OpenAI Ruby client (ruby-openai gem)
+    class OpenAI
+      def initialize(config, collector)
+        @config = config
+        @collector = collector
+      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_registered, true)
+
+        # Wrap the chat method
+        wrap_chat_method(client)
+
+        client
+      end
+
+      private
+
+      def validate_client!(client)
+        return if client.respond_to?(:chat)
+
+        raise RegistrationError, "Client does not appear to be a valid OpenAI client (missing chat method)"
+      end
+
+      def wrap_chat_method(client)
+        client.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_chat, :chat
+
+          define_method(:chat) do |parameters: {}|
+            start_time = Time.now
+
+            # Call original method
+            response = original_chat(parameters: parameters)
+
+            # Submit analytics
+            payloop_submit_analytics(
+              provider: "openai",
+              method: :chat,
+              args: [],
+              kwargs: { parameters: parameters },
+              response: response,
+              start_time: start_time,
+              end_time: Time.now
+            )
+
+            response
+          rescue StandardError => e
+            payloop_submit_error_analytics(
+              provider: "openai",
+              method: :chat,
+              args: [],
+              kwargs: { parameters: parameters },
+              error: e,
+              start_time: start_time,
+              end_time: Time.now
+            )
+
+            raise e
+          end
+        end
+      end
+    end
+  end
+end

data/lib/payloop.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "payloop/version"
+require_relative "payloop/errors"
+require_relative "payloop/config"
+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/api/base"
+require_relative "payloop/api/workflows"
+require_relative "payloop/api/invocation"
+require_relative "payloop/api/workflow"
+require_relative "payloop/client"
+
+# Payloop - Cost visibility for AI agents
+#
+# Payloop is a lightweight infrastructure layer that gives AI teams
+# real-time visibility into the true costs of deploying agents.
+#
+# @example Basic usage with OpenAI
+#   require 'openai'
+#   require 'payloop'
+#
+#   openai = OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
+#   payloop = Payloop::Client.new(api_key: ENV['PAYLOOP_API_KEY'])
+#   payloop.openai.register(openai)
+#
+#   # Use OpenAI normally - analytics tracked automatically
+#   response = openai.chat(
+#     parameters: {
+#       model: "gpt-4",
+#       messages: [{ role: "user", content: "Hello!" }]
+#     }
+#   )
+#
+# @example With attribution
+#   payloop.attribution(
+#     parent_id: "user-123",
+#     parent_name: "John Doe"
+#   )
+#
+# @see https://developers.trypayloop.com
+module Payloop
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: payloop
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Payloop
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: Payloop gives AI teams real-time visibility into the true costs of deploying
+  agents - across tasks, workflows, and customers.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/payloop.rb
+- lib/payloop/api/base.rb
+- lib/payloop/api/invocation.rb
+- lib/payloop/api/workflow.rb
+- lib/payloop/api/workflows.rb
+- lib/payloop/attribution.rb
+- lib/payloop/client.rb
+- lib/payloop/collector.rb
+- lib/payloop/config.rb
+- lib/payloop/errors.rb
+- lib/payloop/version.rb
+- lib/payloop/wrappers/anthropic.rb
+- lib/payloop/wrappers/base.rb
+- lib/payloop/wrappers/google.rb
+- lib/payloop/wrappers/openai.rb
+homepage: https://trypayloop.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://trypayloop.com
+  documentation_uri: https://developers.trypayloop.com
+  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: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Cost visibility for AI agents
+test_files: []