payloop 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7783fa796b37bc909b7902b2477e59eeadb7b28460f4867cece51629b50e114f
-  data.tar.gz: 69871d85d4066f899cf697179ed3468b7adad4420319ee5c2c50f0a11314f8b3
+  metadata.gz: dc7fddc9f323048d0b9930cfa546f569407e82f6114b88c9700e0d635ac04df0
+  data.tar.gz: 306b03a60258ad5ea53ad8fc1cc97efd9c9959c4b517a17c04a1b37c7fde2084
 SHA512:
-  metadata.gz: afc394253b0c42ea0e4bf41dc9c7cfee11dad20dccffbd6689e9c5e3f19ccde79d2a1b1b807b8b07dab83562f8242286047efe6716de476882134be384d1610d
-  data.tar.gz: c98627c98fedec6e77e0b152614dcc1bce1adebe149344c344e10f99e8292607aa35e600da32cb29f9c74d77541de1474b79b5cfdfb519e129b0fdc6b8bd7aeb
+  metadata.gz: 96b3bcb520e6e0e062bad34f56f1a5487c466881b7e29eaf4e2b33d98ecda3a4188ec52db19242f6bd10e45cecff1b029c62e223a7ae7664d630f92454ceeed0
+  data.tar.gz: 576e9946a609e38d998979ce71480c08513e263ac2b6fa0421303ba9c26b228b0035c3acbc9898a375f923d1a80ab577b69d2f6edce8e3affad367a00c4562eb

data/CHANGELOG.md

@@ -51,3 +51,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Support for the RubyLLM library
+
+## [0.3.0] - 2026-04-15
+
+### Added
+- Support OpenAI Responses API (responses.create)
+
+## [0.4.0] - 2026-05-19
+
+### Added
+- Support for the Groq Ruby client (`groq` gem, drnic/groq-ruby), including streaming.
+- RBS type signatures shipped with the gem.

data/lib/payloop/api/invocation.rb

@@ -7,7 +7,7 @@ module Payloop
     # API client for workflow invocation operations
     class Invocation < Base
       def initialize(api_url, api_key, timeout)
-        super(api_url, api_key, timeout)
+        super
         @attribution = nil
       end
 
@@ -35,9 +35,7 @@ module Payloop
           }
         }
 
-        if date_end
-          body[:date][:end] = format_date(date_end)
-        end
+        body[:date][:end] = format_date(date_end) if date_end
 
         body[:attribution] = @attribution if @attribution
 

data/lib/payloop/attribution.rb

@@ -38,7 +38,8 @@ module Payloop
 
       value_str = value.to_s
       if value_str.length > 100
-        raise ValidationError, "parent_id cannot exceed 100 characters (got #{value_str.length})"
+        raise ValidationError,
+              "parent_id cannot exceed 100 characters (got #{value_str.length})"
       end
 
       value_str
@@ -49,7 +50,8 @@ module Payloop
 
       value_str = value.to_s
       if value_str.length > 100
-        raise ValidationError, "#{field_name} cannot exceed 100 characters (got #{value_str.length})"
+        raise ValidationError,
+              "#{field_name} cannot exceed 100 characters (got #{value_str.length})"
       end
 
       value_str

data/lib/payloop/client.rb

@@ -52,6 +52,13 @@ module Payloop
       @ruby_llm ||= Wrappers::RubyLLM.new(@config, @collector, @sentinel)
     end
 
+    # Groq provider wrapper (groq gem, drnic/groq-ruby)
+    # Groq hosts third-party models (Meta Llama, OpenAI gpt-oss, Qwen, etc.).
+    # Telemetry sets provider="groq" and title from the model-ID prefix.
+    def groq
+      @groq ||= Wrappers::Groq.new(@config, @collector, @sentinel)
+    end
+
     # Set attribution for cost tracking
     def attribution(parent_id:, parent_name: nil, subsidiary_id: nil, subsidiary_name: nil)
       attr = Attribution.new(

data/lib/payloop/config.rb

@@ -9,8 +9,16 @@ module Payloop
 
     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"
+      # URL precedence: constructor arg > PAYLOOP_*_URL_BASE env var > hardcoded
+      # prod default. Matches the JS SDK so an integration-test run pointed at
+      # staging or a local backend only requires setting the env vars in
+      # `.env` — no spec changes needed.
+      @collector_url = collector_url ||
+                       nonempty_env("PAYLOOP_COLLECTOR_URL_BASE") ||
+                       "https://collector.trypayloop.com"
+      @api_url = api_url ||
+                 nonempty_env("PAYLOOP_API_URL_BASE") ||
+                 "https://api.trypayloop.com"
       @timeout = timeout || 5
       @version = Payloop::VERSION
       @attribution = Concurrent::AtomicReference.new(nil)
@@ -54,5 +62,18 @@ module Payloop
     def new_transaction
       @tx_uuid.set(SecureRandom.uuid)
     end
+
+    private
+
+    # Returns ENV[name] unless it's missing or empty. We can't use the JS-style
+    # `ENV[name] || default` because Ruby treats empty strings as truthy — and
+    # the `.env.example` ships with blank values for the URL keys, so naïve
+    # truthiness would route every request to "".
+    def nonempty_env(name)
+      value = ENV.fetch(name, nil)
+      return nil if value.nil? || value.empty?
+
+      value
+    end
   end
 end

data/lib/payloop/errors.rb

@@ -29,4 +29,7 @@ module Payloop
   end
 
   class PayloopRequestInterceptedError < Error; end
+
+  # Raised when a streaming response ends without the expected terminal event
+  class StreamError < Error; end
 end

data/lib/payloop/sentinel.rb

@@ -13,7 +13,10 @@ module Payloop
       self
     end
 
-    def set_secs_irrelevant_request_timeout(timeout)
+    # Intentional explicit `set_*` verb prefix — matches JS/Python SDK naming
+    # so callers porting code between SDKs see the same surface. See CLAUDE.md
+    # "Python SDK is the source of truth" / known divergences.
+    def set_secs_irrelevant_request_timeout(timeout) # rubocop:disable Naming/AccessorMethodName
       raise TypeError, "timeout must be a Numeric" unless timeout.is_a?(Numeric)
       raise ArgumentError, "timeout must be greater than 0" unless timeout.positive?
 
@@ -50,6 +53,12 @@ module Payloop
             version: version
           },
           request: normalize_request(request)
+        },
+        meta: {
+          sdk: {
+            client: "ruby",
+            version: @config.version
+          }
         }
       }
 

data/lib/payloop/version.rb

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

data/lib/payloop/wrappers/anthropic.rb

@@ -56,11 +56,16 @@ module Payloop
           extend Base unless singleton_class.include?(Base)
 
           start_time = Time.now
+          version = defined?(::Anthropic::VERSION) ? ::Anthropic::VERSION : nil
 
           # 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)
+          sentinel&.raise_if_irrelevant!(
+            title: ANTHROPIC_CLIENT_TITLE,
+            request: params,
+            version: version
+          )
 
           # Call original method
           response = if kwargs.any?
@@ -77,7 +82,8 @@ module Payloop
             response: response,
             start_time: start_time,
             end_time: Time.now,
-            title: ANTHROPIC_CLIENT_TITLE
+            title: ANTHROPIC_CLIENT_TITLE,
+            version: version
           )
 
           response
@@ -94,7 +100,8 @@ module Payloop
             error: e,
             start_time: start_time,
             end_time: Time.now,
-            title: ANTHROPIC_CLIENT_TITLE
+            title: ANTHROPIC_CLIENT_TITLE,
+            version: version
           )
 
           raise e

data/lib/payloop/wrappers/base.rb

@@ -44,7 +44,8 @@ module Payloop
       end
 
       def payloop_submit_analytics(method:, args:, kwargs:, response:, start_time:,
-                                   end_time:, provider: nil, title: nil)
+                                   end_time:, provider: nil, title: nil, version: nil,
+                                   status: "succeeded", exception: nil)
         collector = instance_variable_get(:@payloop_collector)
         config = instance_variable_get(:@payloop_config)
 
@@ -56,34 +57,38 @@ module Payloop
           start_time: start_time,
           end_time: end_time,
           config: config,
-          status: "succeeded",
+          status: status,
           provider: provider,
-          title: title
+          title: title,
+          version: version,
+          exception: exception
         )
 
         collector.submit_async(payload)
       end
 
+      # Submit a failed-call payload to the collector. `response:` is optional —
+      # when omitted, the default `{ error:, class: }` shape is used. Wrappers
+      # that preserve richer data on error (e.g. Groq's streaming wrapper
+      # merging accumulated chunks with error info via build_error_response)
+      # pass it explicitly; the backend extractor reads whatever fields it can
+      # from the supplied hash and falls back gracefully on missing keys.
       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)
-
-        return unless collector && config
-
-        payload = build_payload(
-          query: extract_query(method, args, kwargs),
-          response: { error: error.message, class: error.class.name },
+                                         end_time:, provider: nil, title: nil, version: nil,
+                                         response: nil)
+        payloop_submit_analytics(
+          method: method,
+          args: args,
+          kwargs: kwargs,
+          response: response || { error: error.message, class: error.class.name },
           start_time: start_time,
           end_time: end_time,
-          config: config,
-          status: "failed",
           provider: provider,
           title: title,
+          version: version,
+          status: "failed",
           exception: error.message
         )
-
-        collector.submit_async(payload)
       end
 
       def payloop_merge_streaming_chunk(accumulated, chunk)
@@ -115,14 +120,14 @@ module Payloop
             next unless choice.is_a?(Hash) && choice.key?("delta")
 
             delta = choice["delta"]
-            if delta.is_a?(Hash)
-              # Add missing keys with nil values to match Python SDK
-              delta["role"] ||= nil unless delta.key?("role")
-              delta["content"] ||= nil unless delta.key?("content")
-              delta["refusal"] ||= nil unless delta.key?("refusal")
-              delta["tool_calls"] ||= nil unless delta.key?("tool_calls")
-              delta["function_call"] ||= nil unless delta.key?("function_call")
-            end
+            next unless delta.is_a?(Hash)
+
+            # Add missing keys with nil values to match Python SDK
+            delta["role"] ||= nil unless delta.key?("role")
+            delta["content"] ||= nil unless delta.key?("content")
+            delta["refusal"] ||= nil unless delta.key?("refusal")
+            delta["tool_calls"] ||= nil unless delta.key?("tool_calls")
+            delta["function_call"] ||= nil unless delta.key?("function_call")
           end
         end
 
@@ -215,14 +220,14 @@ module Payloop
       # - 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)
+                        provider: nil, title: nil, version: nil, exception: nil)
         {
           attribution: config.attribution&.to_h,
           conversation: {
             client: {
               provider: provider,
               title: title,
-              version: nil
+              version: version
             },
             query: query,
             response: response

data/lib/payloop/wrappers/constants.rb

@@ -7,5 +7,6 @@ module Payloop
     ANTHROPIC_CLIENT_TITLE = "anthropic"
     GOOGLE_CLIENT_TITLE = "google"
     RUBY_LLM_PROVIDER = "ruby_llm"
+    GROQ_PROVIDER = "groq"
   end
 end

data/lib/payloop/wrappers/geminiai.rb

@@ -37,7 +37,8 @@ module Payloop
         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
+              "Client does not appear to be a valid Gemini AI client " \
+              "(missing generate_content or stream_generate_content method)"
       end
 
       def wrap_generate_content_method(client)
@@ -57,9 +58,14 @@ module Payloop
                          end
 
             start_time = Time.now
+            version = defined?(::Gemini::GEM) && ::Gemini::GEM.is_a?(Hash) ? ::Gemini::GEM[:version] : nil
 
             sentinel = instance_variable_get(:@payloop_sentinel)
-            sentinel&.raise_if_irrelevant!(title: GOOGLE_CLIENT_TITLE, request: parameters)
+            sentinel&.raise_if_irrelevant!(
+              title: GOOGLE_CLIENT_TITLE,
+              request: parameters,
+              version: version
+            )
 
             # Call original method
             response = original_generate_content(*args, **kwargs, &block)
@@ -72,7 +78,8 @@ module Payloop
               response: response,
               start_time: start_time,
               end_time: Time.now,
-              title: GOOGLE_CLIENT_TITLE
+              title: GOOGLE_CLIENT_TITLE,
+              version: version
             )
 
             response
@@ -87,7 +94,8 @@ module Payloop
               error: e,
               start_time: start_time,
               end_time: Time.now,
-              title: GOOGLE_CLIENT_TITLE
+              title: GOOGLE_CLIENT_TITLE,
+              version: version
             )
 
             raise e
@@ -116,9 +124,14 @@ module Payloop
                          end
 
             start_time = Time.now
+            version = defined?(::Gemini::GEM) && ::Gemini::GEM.is_a?(Hash) ? ::Gemini::GEM[:version] : nil
 
             sentinel = instance_variable_get(:@payloop_sentinel)
-            sentinel&.raise_if_irrelevant!(title: GOOGLE_CLIENT_TITLE, request: parameters)
+            sentinel&.raise_if_irrelevant!(
+              title: GOOGLE_CLIENT_TITLE,
+              request: parameters,
+              version: version
+            )
 
             # Call original method with wrapped block
             response = original_stream_generate_content(*args, **kwargs, &block)
@@ -131,7 +144,8 @@ module Payloop
               response: response,
               start_time: start_time,
               end_time: Time.now,
-              title: GOOGLE_CLIENT_TITLE
+              title: GOOGLE_CLIENT_TITLE,
+              version: version
             )
 
             response
@@ -146,7 +160,8 @@ module Payloop
               error: e,
               start_time: start_time,
               end_time: Time.now,
-              title: GOOGLE_CLIENT_TITLE
+              title: GOOGLE_CLIENT_TITLE,
+              version: version
             )
 
             raise e

data/lib/payloop/wrappers/google.rb

@@ -49,8 +49,10 @@ module Payloop
         return if ::Google::Genai::Types::GenerateContentResponse.instance_variable_defined?(:@_payloop_patched)
 
         ::Google::Genai::Types::GenerateContentResponse.class_eval do
-          # Use camelCase to match Google's API response keys
-          attr_accessor :modelVersion, :usageMetadata, :responseId, :createTime
+          # camelCase intentional — these names must match Google's API response
+          # keys verbatim so the patched accessors survive serialization through
+          # `Base#extract_response`.
+          attr_accessor :modelVersion, :usageMetadata, :responseId, :createTime # rubocop:disable Naming/MethodName
         end
 
         ::Google::Genai::Types::GenerateContentResponse.instance_variable_set(:@_payloop_patched, true)
@@ -74,12 +76,17 @@ module Payloop
           extend Base unless singleton_class.include?(Base)
 
           start_time = Time.now
+          version = defined?(::Google::Genai::VERSION) ? ::Google::Genai::VERSION : nil
 
           # 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)
+          sentinel&.raise_if_irrelevant!(
+            title: GOOGLE_CLIENT_TITLE,
+            request: params,
+            version: version
+          )
 
           # Call original method
           response = if kwargs.any?
@@ -96,7 +103,8 @@ module Payloop
             response: response,
             start_time: start_time,
             end_time: Time.now,
-            title: GOOGLE_CLIENT_TITLE
+            title: GOOGLE_CLIENT_TITLE,
+            version: version
           )
 
           response
@@ -113,7 +121,8 @@ module Payloop
             error: e,
             start_time: start_time,
             end_time: Time.now,
-            title: GOOGLE_CLIENT_TITLE
+            title: GOOGLE_CLIENT_TITLE,
+            version: version
           )
 
           raise e