payloop 0.1.1 → 0.4.0

data/lib/payloop/wrappers/groq.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Payloop
+  module Wrappers
+    # Wrapper for the Groq Ruby client (`groq` gem, drnic/groq-ruby).
+    #
+    # Groq is an inference framework that hosts third-party models (Meta Llama,
+    # OpenAI gpt-oss, Qwen, compound systems), so it sits in
+    # `conversation.client.provider = "groq"` rather than `title`. `title` is
+    # derived per-call from the model-ID prefix — e.g.
+    # `meta-llama/llama-4-scout-17b-16e-instruct` → `"meta-llama"`,
+    # `openai/gpt-oss-20b` → `"openai"`. Legacy un-prefixed IDs
+    # (`llama-3.1-8b-instant`, `allam-2-7b`) fall back to the first
+    # alphanumeric run (`"llama"`, `"allam"`); anything unparseable falls
+    # back to `GROQ_PROVIDER` (`"groq"`). `title` is never nil.
+    #
+    # Unlike the JS / Python groq-sdk, the Ruby `groq` gem's `Client#chat`
+    # returns only the assistant message hash (`response.body.dig("choices", 0,
+    # "message")`), discarding `usage`, `model`, and the rest of the chat
+    # completion envelope. To preserve the wire shape the backend extractor
+    # expects, we patch the lower-level `Client#post(path:, body:)` and filter
+    # by path — every chat call goes through `/openai/v1/chat/completions`, and
+    # `body`/`response.body` at that layer carry the full chat-completion
+    # request and response.
+    class Groq
+      # HTTP path for Groq's chat-completion endpoint (Groq's API is OpenAI-compatible,
+      # namespaced under `/openai/v1/`). The `post` wrapper filters on this so non-chat
+      # requests pass through without analytics or sentinel.
+      CHAT_COMPLETIONS_PATH = "/openai/v1/chat/completions"
+
+      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)
+
+        # Patch the gem's streaming JSON parser. Class-level patch on
+        # ::Groq::Client, idempotent via @_payloop_stream_patched — runs once
+        # per process. Placed after the per-client guard so repeat register
+        # calls on the same client are a true no-op. See patch_stream_handler!
+        # for the bug being worked around.
+        patch_stream_handler!
+
+        # 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_post_method(client)
+
+        client
+      end
+
+      # Derive a telemetry `title` from a Groq model identifier. Mirrors
+      # `extractModelTitle` in the JS SDK (`javascript-sdk/src/utils.ts`).
+      #
+      # Rules:
+      #   - String with `/`: return everything before the first `/`
+      #     (`meta-llama/llama-4-...` → `"meta-llama"`, `openai/gpt-oss-20b`
+      #     → `"openai"`).
+      #   - String without `/`: return the first run of alphanumeric characters
+      #     (`llama-3.1-8b-instant` → `"llama"`, `allam-2-7b` → `"allam"`,
+      #     `gpt-4o` → `"gpt"`).
+      #   - Anything else (non-string, empty, unrecognized shape): return
+      #     `fallback`.
+      #
+      # Telemetry invariant: `conversation.client.title` is never nil — the
+      # caller always supplies a sensible string fallback (`GROQ_PROVIDER` for
+      # Groq calls).
+      #
+      # Public because the wrapped-method closure (inside
+      # singleton_class.class_eval) needs to call it.
+      def self.extract_model_title(model, fallback)
+        return fallback unless model.is_a?(String)
+
+        slash = model.index("/")
+        return model[0...slash] || fallback if slash&.positive?
+
+        model[/\A[A-Za-z0-9]+/] || fallback
+      end
+
+      # Build the `response` hash sent on a failed call. For streaming requests
+      # that errored after one or more chunks were already merged, the partial
+      # `accumulated` response is preserved and the error info is folded in —
+      # so the backend can record what was generated before the failure.
+      # Non-streaming and pre-chunk failures get the original error-only shape.
+      #
+      # Public for the same reason as `extract_model_title` — invoked from the
+      # wrapped-method closure inside `singleton_class.class_eval`.
+      def self.build_error_response(streaming:, accumulated:, error:)
+        if streaming && accumulated.is_a?(Hash) && !accumulated.empty?
+          accumulated.merge("error" => error.message, "error_class" => error.class.name)
+        else
+          { error: error.message, class: error.class.name }
+        end
+      end
+
+      private
+
+      def validate_client!(client)
+        return if defined?(::Groq::Client) && client.is_a?(::Groq::Client)
+        # Fallback for mock objects in tests — must have both methods.
+        return if client.respond_to?(:chat) && client.respond_to?(:post)
+
+        raise RegistrationError,
+              "Client does not appear to be a valid Groq client (missing chat method)"
+      end
+
+      # The `groq` gem (drnic/groq-ruby v0.3.2) parses each SSE chunk inside
+      # `Client#to_json_stream` with:
+      #
+      #   delta = chunk.dig("choices", 0, "delta")
+      #   content = delta.dig("content")
+      #
+      # That second line crashes with `NoMethodError: undefined method 'dig' for
+      # nil:NilClass` when `delta` is nil — which happens on the terminal usage
+      # chunk Groq sends when `stream_options.include_usage = true` (the chunk
+      # has `choices: []`, so the first `dig` returns nil). Since we inject
+      # `include_usage: true` for JS/Python parity (token counts), this fires
+      # on every real streaming call. Replace the method with a copy that uses
+      # `delta&.dig("content")`. Idempotent via `@_payloop_stream_patched`.
+      def patch_stream_handler!
+        return unless defined?(::Groq::Client)
+        return if ::Groq::Client.instance_variable_defined?(:@_payloop_stream_patched)
+
+        # The gem lazy-loads event_stream_parser inside Client#chat. Our patched
+        # to_json_stream needs the constant available at the patch's class_eval
+        # site too, so eagerly require it now.
+        require "event_stream_parser"
+
+        ::Groq::Client.class_eval do
+          private
+
+          def to_json_stream(user_proc:)
+            parser = ::EventStreamParser::Parser.new
+
+            proc do |chunk, _bytes, env|
+              if env && env.status != 200
+                raise_error = Faraday::Response::RaiseError.new
+                raise_error.on_complete(env.merge(body: try_parse_json(chunk)))
+              end
+
+              parser.feed(chunk) do |_type, data|
+                next if data == "[DONE]"
+
+                chunk = JSON.parse(data)
+                delta = chunk.dig("choices", 0, "delta")
+                content = delta&.dig("content")
+
+                arity = user_proc.is_a?(Proc) ? user_proc.arity : user_proc.method(:call).arity
+                if arity == 1
+                  user_proc.call(content)
+                else
+                  user_proc.call(content, chunk)
+                end
+              end
+            end
+          end
+        end
+
+        ::Groq::Client.instance_variable_set(:@_payloop_stream_patched, true)
+      end
+
+      def wrap_post_method(client)
+        chat_path = CHAT_COMPLETIONS_PATH
+
+        client.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_post, :post
+
+          define_method(:post) do |path:, body:|
+            # Non-chat-completions paths pass through untouched — no analytics,
+            # no sentinel. (At time of writing the gem only ever uses post for
+            # chat completions, but be defensive about future endpoints.)
+            return original_post(path: path, body: body) unless path == chat_path
+
+            start_time = Time.now
+            version = defined?(::Groq::VERSION) ? ::Groq::VERSION : nil
+            title = Payloop::Wrappers::Groq.extract_model_title(body[:model], GROQ_PROVIDER)
+
+            sentinel = instance_variable_get(:@payloop_sentinel)
+            sentinel&.raise_if_irrelevant!(
+              title: title,
+              request: body,
+              provider: GROQ_PROVIDER,
+              version: version
+            )
+
+            # Dup before mutating so the caller's body hash is unchanged.
+            body = body.dup
+            streaming = body[:stream_chunk].respond_to?(:call)
+            accumulated_response = streaming ? {} : nil
+
+            if streaming
+              # Match the JS/Python behavior: ask Groq to include usage on the
+              # terminal chunk so the merged response carries token counts.
+              # A caller-set value (true or false) wins — we only force `true`
+              # when the key is absent.
+              body[:stream_options] = { include_usage: true }.merge(body[:stream_options] || {})
+
+              user_callback = body[:stream_chunk]
+              body[:stream_chunk] = proc do |content, chunk|
+                if chunk.is_a?(Hash)
+                  normalized = payloop_normalize_openai_chunk(chunk)
+                  payloop_merge_streaming_chunk(accumulated_response, normalized)
+                end
+
+                # The gem inspects user_proc.arity to decide between
+                # call(content) and call(content, chunk); forward with the
+                # caller's intended signature.
+                arity = user_callback.is_a?(Proc) ? user_callback.arity : user_callback.method(:call).arity
+                if arity == 1
+                  user_callback.call(content)
+                else
+                  user_callback.call(content, chunk)
+                end
+              end
+            end
+
+            response = original_post(path: path, body: body)
+
+            final_response = if streaming
+                               accumulated_response
+                             elsif response.respond_to?(:body)
+                               response.body
+                             else
+                               response
+                             end
+
+            # Sanitize body for analytics: stream_chunk is a Proc and the
+            # collector would fail to JSON-encode it. Mirror the OpenAI
+            # wrapper's `:stream` → `true` collapse.
+            analytics_body = body.dup
+            analytics_body[:stream_chunk] = true if analytics_body[:stream_chunk].respond_to?(:call)
+
+            payloop_submit_analytics(
+              method: :post,
+              args: [],
+              kwargs: analytics_body,
+              response: final_response,
+              start_time: start_time,
+              end_time: Time.now,
+              provider: GROQ_PROVIDER,
+              title: title,
+              version: version
+            )
+
+            response
+          rescue PayloopRequestInterceptedError => e
+            # We don't want to send intercepts to collector
+            raise e
+          rescue StandardError => e
+            analytics_body = body.dup
+            analytics_body[:stream_chunk] = true if analytics_body[:stream_chunk].respond_to?(:call)
+
+            # On streaming failure after one or more chunks merged, pass the
+            # accumulated response (plus error info) through so the backend
+            # extractor can pull partial assistant content / token usage from
+            # what was received before the error. Non-streaming and
+            # pre-chunk failures fall back to the helper's default
+            # `{error, class}` shape.
+            error_response = Payloop::Wrappers::Groq.build_error_response(
+              streaming: streaming, accumulated: accumulated_response, error: e
+            )
+
+            payloop_submit_error_analytics(
+              method: :post,
+              args: [],
+              kwargs: analytics_body,
+              error: e,
+              start_time: start_time,
+              end_time: Time.now,
+              provider: GROQ_PROVIDER,
+              title: title,
+              version: version,
+              response: error_response
+            )
+
+            raise e
+          end
+        end
+      end
+    end
+  end
+end

data/lib/payloop/wrappers/openai.rb

@@ -27,12 +27,141 @@ module Payloop
         # Wrap the chat method
         wrap_chat_method(client)
 
+        # Wrap responses.create if the client supports the Responses API (ruby-openai >= 8.0)
+        wrap_responses_method(client) if client.respond_to?(:responses)
+
         client
       end
 
       private
 
+      def wrap_responses_method(client)
+        responses_obj = client.responses
+
+        # Copy Payloop references onto the responses sub-object so Base helpers can access them
+        responses_obj.instance_variable_set(:@payloop_config, client.instance_variable_get(:@payloop_config))
+        responses_obj.instance_variable_set(:@payloop_collector, client.instance_variable_get(:@payloop_collector))
+        responses_obj.instance_variable_set(:@payloop_sentinel, client.instance_variable_get(:@payloop_sentinel))
+
+        responses_obj.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_create, :create
+
+          define_method(:create) do |parameters: {}|
+            start_time = Time.now
+            version = defined?(::OpenAI::VERSION) ? ::OpenAI::VERSION : nil
+
+            sentinel = instance_variable_get(:@payloop_sentinel)
+            sentinel&.raise_if_irrelevant!(
+              title: OPENAI_CLIENT_TITLE,
+              request: parameters,
+              version: version
+            )
+
+            # Dup before mutating so we don't replace the caller's :stream key with our
+            # internal wrapping proc — the caller's hash should be unchanged after the call.
+            parameters = parameters.dup
+
+            streaming = parameters[:stream].respond_to?(:call)
+
+            if streaming
+              accumulated_events = []
+              user_callback = parameters[:stream]
+              # Determine how many arguments to forward to the user's callback.
+              # .arity returns negative values for methods with optional/splat params
+              # (e.g. def call(*args) => -1, def call(a, b=nil) => -2), so .abs gives
+              # us the minimum required argument count. For fixed-arity procs/lambdas
+              # this is exact. Note: a variadic callable (def call(*args)) has arity -1,
+              # so .abs yields 1 — the event_type argument will be silently dropped for
+              # that signature. Use def call(event, event_type = nil) to receive both.
+              user_callback_arity =
+                case user_callback
+                when Proc
+                  user_callback.arity.abs
+                else
+                  user_callback.method(:call).arity.abs
+                end
+
+              parameters[:stream] = proc do |chunk, event_type|
+                accumulated_events << chunk if chunk.is_a?(Hash)
+                user_callback.call(*[chunk, event_type].first(user_callback_arity))
+              end
+            end
+
+            response = original_create(parameters: parameters)
+
+            # Default to the returned response; for streaming, replace it with the
+            # full response from the terminal response.completed event.
+            final_response = response
+
+            if streaming
+              error_event = accumulated_events.find { |e| e["type"] == "error" }
+              if error_event
+                final_response = {
+                  "status" => "failed",
+                  "error" => error_event["error"]
+                }
+              end
+
+              # Extract the full response from the terminal response.completed event.
+              # A missing terminal event means the stream was interrupted.
+              completed = accumulated_events.find { |e| e["type"] == "response.completed" }
+              unless completed || error_event
+                raise StreamError,
+                      "Responses API stream ended without response.completed event"
+              end
+
+              final_response = completed["response"] if completed && !error_event
+            end
+
+            # Treat only an explicit failed response status as failed analytics.
+            # Other non-exceptional statuses are still recorded as succeeded.
+            response_status = final_response.is_a?(Hash) ? final_response["status"] : nil
+            analytics_status = response_status == "failed" ? "failed" : "succeeded"
+            analytics_exception =
+              if analytics_status == "failed"
+                final_response.dig("error", "message") ||
+                  "OpenAI response status: #{response_status || "unknown"}"
+              end
+
+            payloop_submit_analytics(
+              method: :create,
+              args: [],
+              kwargs: parameters,
+              response: final_response,
+              start_time: start_time,
+              end_time: Time.now,
+              title: OPENAI_CLIENT_TITLE,
+              version: version,
+              status: analytics_status,
+              exception: analytics_exception
+            )
+
+            response
+          rescue PayloopRequestInterceptedError => e
+            raise e
+          rescue StandardError => e
+            payloop_submit_error_analytics(
+              method: :create,
+              args: [],
+              kwargs: parameters,
+              error: e,
+              start_time: start_time,
+              end_time: Time.now,
+              title: OPENAI_CLIENT_TITLE,
+              version: version
+            )
+            raise e
+          end
+        end
+      end
+
       def validate_client!(client)
+        # When register an OpenAI client, it currently only checks if there
+        # is the classic "chat" interface.  OpenAI now supports the newer
+        # "responses" interface.  So, if an OpenAI client later only has
+        # the newer "responses" interface, this validate_client will fail.
         return if client.respond_to?(:chat)
 
         raise RegistrationError, "Client does not appear to be a valid OpenAI client (missing chat method)"
@@ -46,18 +175,25 @@ module Payloop
 
           define_method(:chat) do |parameters: {}|
             start_time = Time.now
+            version = defined?(::OpenAI::VERSION) ? ::OpenAI::VERSION : nil
 
             sentinel = instance_variable_get(:@payloop_sentinel)
-            sentinel&.raise_if_irrelevant!(title: OPENAI_CLIENT_TITLE, request: parameters)
+            sentinel&.raise_if_irrelevant!(
+              title: OPENAI_CLIENT_TITLE,
+              request: parameters,
+              version: version
+            )
 
             # Detect streaming and wrap callback to accumulate chunks
             streaming = parameters[:stream].is_a?(Proc)
             accumulated_response = {} if streaming
 
             if streaming
-              # Configure streaming to include usage (matches Python SDK behavior)
+              # Configure streaming to include usage (matches Python SDK behavior).
+              # A caller-set value (true or false) wins — we only force `true`
+              # when the key is absent.
               parameters[:stream_options] ||= {}
-              parameters[:stream_options][:include_usage] = true
+              parameters[:stream_options][:include_usage] = true unless parameters[:stream_options].key?(:include_usage)
 
               user_callback = parameters[:stream]
               parameters[:stream] = proc do |chunk, bytesize|
@@ -70,7 +206,7 @@ module Payloop
               end
             end
 
-            # Call original method
+            # Call the original method
             response = original_chat(parameters: parameters)
 
             # Use accumulated response for streaming, otherwise use returned response
@@ -84,7 +220,8 @@ module Payloop
               response: final_response,
               start_time: start_time,
               end_time: Time.now,
-              title: OPENAI_CLIENT_TITLE
+              title: OPENAI_CLIENT_TITLE,
+              version: version
             )
 
             response
@@ -99,7 +236,8 @@ module Payloop
               error: e,
               start_time: start_time,
               end_time: Time.now,
-              title: OPENAI_CLIENT_TITLE
+              title: OPENAI_CLIENT_TITLE,
+              version: version
             )
 
             raise e

data/lib/payloop/wrappers/ruby_llm.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Payloop
+  module Wrappers
+    # Wrapper for RubyLLM (ruby_llm gem)
+    # Supports any provider available via RubyLLM (Anthropic, OpenAI, Google, etc.)
+    # Returns raw response and raw formatted query to backend so that the existing
+    # extractors can be used.
+    class RubyLLM
+      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 the 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)
+
+        # Ask method handles both streaming and non-streaming cases unlike some others.
+        wrap_ask_method(client)
+
+        client
+      end
+
+      private
+
+      def validate_client!(client)
+        return if client.respond_to?(:ask)
+
+        raise RegistrationError,
+              "Client does not appear to be a valid RubyLLM client (missing ask method)"
+      end
+
+      def wrap_ask_method(client)
+        # Capture the wrapper instance in a local variable so it's accessible as a closure
+        # inside the block, where self will no longer refer to it.
+        wrapper = self
+
+        client.singleton_class.class_eval do
+          include Base
+
+          alias_method :original_ask, :ask
+
+          define_method(:ask) do |message, with: nil, &block|
+            start_time = Time.now
+            query = {} # Fallback for error analytics if an exception occurs before build_query completes
+            # Version reported is RubyLLM's, not the underlying provider's — RubyLLM is the
+            # meta-wrapper Payloop sees; the native provider gem may not even be loaded.
+            version = defined?(::RubyLLM::VERSION) ? ::RubyLLM::VERSION : nil
+
+            sentinel = instance_variable_get(:@payloop_sentinel)
+            provider = model.provider
+            # Telemetry invariant: `conversation.client.title` is never nil.
+            # `model.provider` should always return a non-empty string for
+            # well-formed RubyLLM models, but fall back to the meta-wrapper
+            # name (matches JS's pattern of "fallback to the SDK family
+            # name") if it ever isn't.
+            title = case provider
+                    when "gemini" then GOOGLE_CLIENT_TITLE
+                    when nil, "" then RUBY_LLM_PROVIDER
+                    else provider
+                    end
+
+            # Capture existing messages (e.g. system instruction) before the call
+            # adds the new user message to history.
+            existing_msgs = messages.map { |m| { role: m.role.to_s, content: m.content.to_s } }
+            all_msgs = existing_msgs + [{ role: "user", content: message.to_s }]
+
+            # Build a query in the provider's native format so the backend extractor can parse it.
+            query = wrapper.send(:build_query, provider, model.id, all_msgs, tools)
+
+            # Pass the actual provider title (e.g. "anthropic", "openai", "google") so the
+            # sentinel backend can route to the correct classifier for this request format.
+            sentinel&.raise_if_irrelevant!(title: title, request: query, version: version)
+
+            response = original_ask(message, with: with, &block)
+
+            payloop_submit_analytics(
+              method: :ask,
+              args: [],
+              kwargs: query,
+              response: response.raw&.body,
+              start_time: start_time,
+              end_time: Time.now,
+              title: title,
+              provider: RUBY_LLM_PROVIDER,
+              version: version
+            )
+
+            response
+          rescue PayloopRequestInterceptedError => e
+            raise e
+          rescue StandardError => e
+            payloop_submit_error_analytics(
+              method: :ask,
+              args: [],
+              kwargs: query,
+              error: e,
+              start_time: start_time,
+              end_time: Time.now,
+              title: title,
+              provider: RUBY_LLM_PROVIDER,
+              version: version
+            )
+            raise e
+          end
+        end
+      end
+
+      # Dispatches to the appropriate provider-native query builder.
+      def build_query(provider, model_id, messages, tools)
+        if provider == "gemini"
+          build_google_query(model_id, messages, tools)
+        else
+          # Anthropic and OpenAI have the same query format
+          build_messages_query(model_id, messages, tools)
+        end
+      end
+
+      # Builds an OpenAI-compatible query (used for Anthropic and OpenAI providers).
+      def build_messages_query(model_id, messages, tools)
+        query = { model: model_id, messages: messages }
+        unless tools.empty?
+          query[:tools] = tools.values.map do |t|
+            { name: t.name, description: t.description, parameters: t.params_schema }
+          end
+        end
+        query
+      end
+
+      # Builds a Google-native query with contents/systemInstruction structure.
+      def build_google_query(model_id, messages, tools)
+        system_msgs = messages.select { |m| m[:role] == "system" }
+        content_msgs = messages.reject { |m| m[:role] == "system" }
+
+        query = {
+          model: model_id,
+          contents: content_msgs.map do |m|
+            google_role = m[:role] == "assistant" ? "model" : m[:role]
+            { role: google_role, parts: [{ text: m[:content] }] }
+          end
+        }
+
+        if system_msgs.any?
+          system_text = system_msgs.map { |m| m[:content] }.join("\n")
+          query[:systemInstruction] = { parts: [{ text: system_text }] }
+        end
+
+        unless tools.empty?
+          query[:tools] = tools.values.map do |t|
+            { name: t.name, description: t.description, parameters: t.params_schema }
+          end
+        end
+
+        query
+      end
+    end
+  end
+end

data/lib/payloop.rb

@@ -11,6 +11,8 @@ require_relative "payloop/wrappers/openai"
 require_relative "payloop/wrappers/anthropic"
 require_relative "payloop/wrappers/google"
 require_relative "payloop/wrappers/geminiai"
+require_relative "payloop/wrappers/ruby_llm"
+require_relative "payloop/wrappers/groq"
 require_relative "payloop/api/base"
 require_relative "payloop/api/sentinel"
 require_relative "payloop/api/workflows"