fast-completions 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d3db818f96038ddf53481fea90ce309a3a01be84d924e8d4707ce121a9232ba
-  data.tar.gz: a6aa0363ad9ba1c6c2b45e47645137390254d8c1b0c8067e8de7f6cc64ed7e43
+  metadata.gz: 296c0ef9c66b4933e440f14845ecca83e7ab18e96f125a572adda19e853be9b7
+  data.tar.gz: 12fe00808afa0c4c81a9b36dc3d898803c63dd570fcb29d86292d6c526b96557
 SHA512:
-  metadata.gz: 63a9237cef1bbf316295f96bb6bd13107f5efadef2f0434070070edbd1a74a4668c725d6b7690a73cdfa7d02b750df2c4a85f5a60a1f77b96d0c48d4767c6f20
-  data.tar.gz: 90c846372d3c94697e85de1075d61c7b40525b9c0ad7d2dcc11f632c6204d002e946e5ffb9b62529da0695ebeab930af24413475366ef7d09204f3f233ffefea
+  metadata.gz: 63b785f46a6a15265ddf700f6039d920670059a5a0c39b4b40c92892462577fc9bc1b02c0dc33645be44a28fc991961bdbd437568ed32188081e6b62105f9ba4
+  data.tar.gz: c02fdca12bb4133152fc6f41a4c2c2157e011937b93f2eb2dff319c18bda3124836d2a588386ddf96a00022488f13b31b1623edb609c86b7f0c29ea0d77f33c8

data/CHANGELOG.md

@@ -3,6 +3,36 @@
 Notable changes to the fast-completions gem. The format is prose-first,
 one section per released version, newest first.
 
+## 0.7.0 (2026-10-25)
+
+- Telemetry sink interface: `Client.new` accepts `telemetry:` — any
+  Enumerable of sink objects (an Array, a Set, …), validated loudly at
+  construction (a non-Enumerable, or a
+  sink not responding to all five hooks, raises `ArgumentError` naming
+  the offender and the missing hook; duck-typed sinks are accepted
+  without module inclusion; the client keeps its own frozen Array —
+  `entries` — so the caller's container is never frozen or mutated) — and dispatches five
+  observation hooks around a completion, ONE `Client#stream` invocation
+  (creation retries inside, tool execution outside):
+  `on_completion_start(model.id, body bytesize)` before the first POST,
+  `on_completion_ttfb` at the first parser item of the successful
+  attempt (a retried attempt's clock restarts), `on_event` for every
+  Event — before its consumer twin, terminals and the salvage `:error`
+  included, and even with no consumer block — `on_completion_end(stop
+  reason, duration, live message)` when `stream` returns, and
+  `on_completion_error(error Symbol derived from the raising class,
+  duration)` on every raise-out, cancellation included. Multiple sinks
+  dispatch in registration order. The allocation discipline is pinned
+  by spec measurement gates: zero added heap objects on the hot paths
+  with no sink registered, zero ADDED objects with a no-op sink (only
+  refs and immediates cross the boundary, durations are flonum
+  differences, every call site short-circuits on a precomputed
+  emptiness check), and zero added `Process.clock_gettime` reads. The
+  new reference page `docs/reference/telemetry.md` documents the
+  protocol, the ordering rule (telemetry is the ground-truth record
+  when consumer code is the suspect), the read-only convention for
+  sinks, and that metric naming belongs to the adapter.
+
 ## 0.6.0 (2026-10-25)
 
 - `Client#raw_stream` — the raw completions surface a proxy needs: the

data/lib/fast/completions/client.rb

@@ -58,13 +58,31 @@ module Fast
         Errno::ENETUNREACH, Errno::ETIMEDOUT, EOFError, IOError, SocketError,
       ].freeze
 
+      # The five Telemetry::Sink hooks a registered sink must respond to
+      # (I01). Checked ONCE at construction — the only sanctioned
+      # respond_to? use; notification-time dispatch never reflects.
+      TELEMETRY_HOOKS = %i[
+        on_completion_start on_completion_ttfb on_event on_completion_end on_completion_error
+      ].freeze
+
       attr_reader :timeout, :max_retries, :dropped_chunks, :ttfb_timeout, :inactivity_timeout
 
       def initialize(base_url:, api_key: nil, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES,
-        ttfb_timeout: nil, inactivity_timeout: nil)
+        ttfb_timeout: nil, inactivity_timeout: nil, telemetry: [])
         raise ArgumentError, "max_retries must be an Integer >= 0" unless max_retries.is_a?(Integer) && max_retries >= 0
         validate_deadline!(:ttfb_timeout, ttfb_timeout)
         validate_deadline!(:inactivity_timeout, inactivity_timeout)
+        unless telemetry.is_a?(Enumerable)
+          raise ArgumentError, "telemetry must be an Enumerable of sink objects, got #{telemetry.class}"
+        end
+
+        telemetry.each do |sink|
+          missing = TELEMETRY_HOOKS.reject { |hook| sink.respond_to?(hook) }
+          next if missing.empty?
+
+          raise ArgumentError,
+            "telemetry sink #{sink.inspect} does not respond to #{missing.join(", ")} (Telemetry::Sink hooks)"
+        end
 
         @endpoint = Async::HTTP::Endpoint.parse(base_url)
         @api_key = api_key
@@ -74,6 +92,14 @@ module Fast
         @inactivity_timeout = inactivity_timeout
         @client = Async::HTTP::Client.new(@endpoint)
         @path = @endpoint.path.chomp("/") + "/chat/completions"
+        # I01: the client's own frozen copy (the caller's container is
+        # never frozen or mutated) + the precomputed emptiness check every
+        # call site short-circuits on — zero allocation, zero added
+        # clock reads when no sink is registered. `entries` always
+        # builds a fresh Array — for an Array input too, so any
+        # Enumerable input lands in the same frozen-Array shape.
+        @telemetry = telemetry.entries.freeze
+        @telemetry_active = !@telemetry.empty?
       end
 
       def close
@@ -105,38 +131,40 @@ module Fast
         headers = default_headers.merge(session_headers(model.dialect, session_id))
         body = JSON.generate(request)
         accumulator = Protocol::StreamAccumulator.new(model, model.dialect)
-
+        started_at = notify_start(model.id, body.bytesize) # I01 §1: the completion clock, nil without sinks
         watchdog = Watchdog.new(Async::Task.current, @timeout)
         response = nil
+        post_started_at = nil # the committed attempt's POST clock (I01 §2), set by create_response's yield
         begin
-          # The POST attempt — creation through status receipt (§2),
-          # bounded-retried on pi's trigger set; every final creation
-          # failure raises its mapped error from in there.
-          response = create_response(headers, body, watchdog)
-          yield accumulator.start_event if block # :start precedes every block event (§10.6)
-          feed_stream(response, accumulator, watchdog, &block)
+          response = create_response(headers, body, watchdog) { |t0| post_started_at = t0 }
+          if block || @telemetry_active # :start even blockless (I01 §4); a consumer raise flies to the ladder
+            dispatch_event(accumulator.start_event, &block)
+          end
+          feed_stream(response, accumulator, watchdog, post_started_at, &block)
         rescue Async::Cancel
-          watchdog.fired ? raise(TimeoutError, "no data within #{@timeout}s") : raise(CancelledError, "stream cancelled")
+          if watchdog.fired # I01 §7: fired → timeout, else user cancel (D8); cancel never salvages (AC3)
+            notify_error(:timeout_error, started_at)
+            raise(TimeoutError, "no data within #{@timeout}s")
+          end
+          notify_error(:cancelled_error, started_at)
+          raise(CancelledError, "stream cancelled")
         rescue *NETWORK_ERRORS => e
-          salvage(accumulator, &block) # the :error terminal carries the partial BEFORE the raise (§1)
+          salvage(accumulator, started_at, &block) # the :error terminal carries the partial BEFORE the raise (§1)
+          notify_error(:connection_error, started_at) # I01 §7: the symbol of the ConnectionError about to raise
           raise ConnectionError, "#{e.class}: #{e.message}"
-        rescue StandardError
-          salvage(accumulator, &block) # pi's catch-all: any other streaming failure — same terminal, raised unchanged
+        rescue StandardError => e
+          salvage(accumulator, started_at, &block) # pi's catch-all: same terminal, raised unchanged
+          notify_error(telemetry_symbol_for(e), started_at) # I01 §7: derived from the re-raised class
           raise
         ensure
-          # Complete bodies return the connection to the pool; an aborted
-          # read (cancel/timeout) discards it — a cancelled connection is
-          # never reused (AC3/D8).
-          begin
-            response.finish
-          rescue StandardError, Async::Cancel
-            nil
-          end
+          finish_quietly(response) # nil-safe: no response yet, or an aborted read (AC3/D8)
           watchdog.stop
         end
-        raise TimeoutError, "no data within #{@timeout}s" if watchdog.fired
-
-        deliver_terminal(accumulator, &block)
+        if watchdog.fired # I01 §7: the post-ensure watchdog raise
+          notify_error(:timeout_error, started_at)
+          raise TimeoutError, "no data within #{@timeout}s"
+        end
+        deliver_terminal(accumulator, started_at, &block)
       end
 
       # The raw surface a proxy needs (I03, BRIEF §3): the caller's
@@ -295,19 +323,31 @@ module Fast
         raise CancelledError, "stream cancelled"
       end
 
-      def feed_stream(response, accumulator, watchdog, &block)
+      # The wire read (§3): SSE parse → accumulator → dispatch. TTFB
+      # fires at the FIRST parser-yielded item of the SUCCESSFUL attempt
+      # (I01 §3 — a `[DONE]` sentinel counts; comments and keepalives
+      # never yield items, sse.rb drops them structurally), measured
+      # from that attempt's POST (post_started_at, threaded in from
+      # create_response; a retried attempt's clock restarts), at most
+      # once per completion. Consumer raises here fly to stream's
+      # ladder, which closes the record after salvage.
+      def feed_stream(response, accumulator, watchdog, post_started_at, &block)
         parser = SSE.new
         @dropped_chunks = 0
+        ttfb_fired = false
         response.body.each do |chunk|
           watchdog.arm # re-arm the inactivity read-timeout per chunk (D5)
           parser.push(chunk).each do |item|
+            if @telemetry_active && !ttfb_fired # before this item's dispatches; a flonum difference — no heap
+              ttfb_fired = true
+              notify_ttfb(Process.clock_gettime(Process::CLOCK_MONOTONIC) - post_started_at)
+            end
             next if item == SSE::DONE # terminal token; no payload
 
             json = parse_chunk(item)
             next if json.nil? # dropped (I61): counted, the stream continues
 
-            events = accumulator.consume(json)
-            events.each { |event| yield event } if block
+            accumulator.consume(json).each { |event| dispatch_event(event, &block) }
           end
         end
       end
@@ -337,14 +377,29 @@ module Fast
       # stop and a missing finish both emit :error FIRST, then raise
       # StreamError; otherwise :done with the mapped reason. Cancel never
       # reaches here — it unwinds mid-read with NO terminal event (AC3).
-      def deliver_terminal(accumulator, &block)
+      # I01 §5: every terminal dispatch reaches the sinks (blockless
+      # included), on_completion_error rides the StreamError raise, and
+      # on_completion_end fires after the :done dispatches. The terminal
+      # Events are built only under the observer guard (zero-path
+      # discipline); every yield below is a ladder-UNCOVERED site — this
+      # method runs AFTER the ladder — so dispatch_event closes the
+      # record on a consumer raise here (see dispatch_event).
+      def deliver_terminal(accumulator, started_at, &block)
         events, outcome = accumulator.finish
-        events.each { |event| yield event } if block
-        if outcome[0] == :stream_error
-          yield Event.new(type: :error, reason: :error, message: accumulator.partial) if block
-          raise StreamError.new(outcome[1], stop_reason: :error)
+        if block || @telemetry_active
+          events.each { |event| dispatch_event(event, started_at, closing: true, &block) }
+          if outcome[0] == :stream_error
+            dispatch_event(Event.new(type: :error, reason: :error, message: accumulator.partial),
+              started_at, closing: true, &block)
+            notify_error(:stream_error, started_at) # the symbol of the StreamError about to raise
+          else
+            dispatch_event(Event.new(type: :done, reason: outcome[1], message: accumulator.partial),
+              started_at, closing: true, &block)
+            notify_end(outcome[1], accumulator.partial, started_at) # after the :done dispatches, before the return
+          end
         end
-        yield Event.new(type: :done, reason: outcome[1], message: accumulator.partial) if block
+        raise StreamError.new(outcome[1], stop_reason: :error) if outcome[0] == :stream_error
+
         accumulator.partial
       end
 
@@ -365,6 +420,7 @@ module Fast
         remaining = @max_retries
         loop do
           watchdog.arm # re-armed per attempt: a retried TTFB deadline restarts (D5)
+          t0 = @telemetry_active ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil # I01 §2, guarded (gate 3)
           begin
             response = @client.post(@path, headers: headers, body: body)
           rescue Async::Cancel
@@ -373,12 +429,14 @@ module Fast
             remaining -= 1
             next
           rescue *NETWORK_ERRORS => e
-            # Statusless — no response was received (pi's statusless trigger).
-            raise ConnectionError, "#{e.class}: #{e.message}" if remaining.zero?
+            raise ConnectionError, "#{e.class}: #{e.message}" if remaining.zero? # statusless trigger
             remaining -= 1
             next
           end
-          return response if (200...300).cover?(response.status)
+          if (200...300).cover?(response.status) # committed to streaming: never retried past a 2xx
+            yield(t0) if block_given? # the committed attempt's POST clock → stream's TTFB local (allocation-free)
+            return response
+          end
 
           if retry_response?(response) && remaining.positive?
             finish_quietly(response) # the discarded attempt's connection returns to the pool
@@ -419,16 +477,22 @@ module Fast
       # finalize_blocks — the thinking reasoning_details serialized into
       # the signature, tool arguments finalized — whose end events we
       # discard here, so a salvaged partial replays like a completed one's.
-      def salvage(accumulator)
-        return unless block_given?
+      # The yield below runs INSIDE a rescue arm — ladder-uncovered — so
+      # dispatch_event closes the record on a consumer raise; the early
+      # return keeps the blockless-no-sink path byte-identical (I01 §6).
+      def salvage(accumulator, started_at, &block)
+        return unless block_given? || @telemetry_active # the blockless-no-sink early return (I01 §6)
 
         accumulator.finish
-        yield Event.new(type: :error, reason: :error, message: accumulator.partial)
+        dispatch_event(Event.new(type: :error, reason: :error, message: accumulator.partial),
+          started_at, closing: true, &block)
       end
 
       # Complete bodies return the connection to the pool; an aborted read
       # (cancel/timeout) discards it — a cancelled connection is never
-      # reused (AC3/D8). Same discipline as stream's ensure.
+      # reused (AC3/D8). Serves the discarded retry attempt and stream's
+      # ensure; nil-safe (no response yet → the rescue swallows the
+      # NoMethodError exactly as the inline form did).
       def finish_quietly(response)
         response.finish
       rescue StandardError, Async::Cancel
@@ -442,6 +506,98 @@ module Fast
         body = response.body.read
         raise Errors.class_for_status(response.status, body).new(status: response.status, body: body)
       end
+
+      # ── I01 telemetry dispatch ─────────────────────────────────────
+      # Every helper short-circuits on the precomputed emptiness check
+      # BEFORE any clock read or dispatch: with no sink registered the
+      # call sites cost one no-op method call, zero allocations, zero
+      # Process.clock_gettime reads. Per-completion state (the
+      # completion-start clock, the per-attempt POST clock, the
+      # ttfb-once flag) is threaded as locals/args, never Client ivars
+      # (I03); durations are flonum differences; dispatch is in
+      # registration order; the loop block itself is never materialized,
+      # so a no-op sink adds zero heap objects (gate 2).
+
+      # The ONE event dispatch seam: sinks first, consumer second (I01
+      # §4/§5 — telemetry is the ground-truth record). `closing:` marks
+      # yield sites the rescue ladder does NOT cover — deliver_terminal
+      # runs after it, salvage inside a rescue arm — where a consumer
+      # raise closes the record here (the raiser's symbol) before the
+      # unchanged, backtrace-preserving re-raise; on StandardError only,
+      # the ladder's own catch scope, so cancel and Exception-class
+      # raises keep today's escape semantics. At the ladder-covered
+      # sites the StandardError arm does the closing (after salvage) —
+      # closing here too would double-fire the record. Dispatch is
+      # implicit yield/block_given? (no captured &block of its own — no
+      # Proc materialization, gate 2); callers forward their
+      # already-captured Proc at the call site, which is free.
+      def dispatch_event(event, started_at = nil, closing: false)
+        return unless block_given? || @telemetry_active
+
+        notify_event(event)
+        if closing
+          begin
+            yield event if block_given?
+          rescue StandardError => e
+            notify_error(telemetry_symbol_for(e), started_at)
+            raise
+          end
+        else
+          yield event if block_given?
+        end
+      end
+
+      # I01 §1: the completion clock (every duration below differs from
+      # it) + on_completion_start, before the first POST of the first
+      # attempt. Returns the clock — nil without a sink, zero added
+      # clock reads (gate 3).
+      def notify_start(model_id, request_bytes)
+        return nil unless @telemetry_active
+
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @telemetry.each { |sink| sink.on_completion_start(model_id, request_bytes) }
+        started_at
+      end
+
+      def notify_ttfb(elapsed)
+        return unless @telemetry_active
+
+        @telemetry.each { |sink| sink.on_completion_ttfb(elapsed) }
+      end
+
+      def notify_event(event)
+        return unless @telemetry_active
+
+        @telemetry.each { |sink| sink.on_event(event) }
+      end
+
+      def notify_end(stop_reason, message, started_at)
+        return unless @telemetry_active
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+        @telemetry.each { |sink| sink.on_completion_end(stop_reason, duration, message) }
+      end
+
+      def notify_error(error, started_at)
+        return unless @telemetry_active
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+        @telemetry.each { |sink| sink.on_completion_error(error, duration) }
+      end
+
+      # The re-raise arm's error Symbol: derived from the raising class —
+      # demodulized, underscored (RateLimitError → :rate_limit_error,
+      # RuntimeError → :runtime_error). Computed only on the raise path,
+      # under the active guard; an anonymous class has no name.
+      def telemetry_symbol_for(error)
+        name = error.class.name
+        return :anonymous_error if name.nil?
+
+        name.split("::").last
+          .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase.to_sym
+      end
     end
   end
 end

data/lib/fast/completions/telemetry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Fast
+  module Completions
+    # The telemetry observation protocol (I01): a sink includes this
+    # module and overrides what it wants — the defaults are no-ops. No
+    # base class, no respond_to? dispatch at notification time (Client
+    # validates the five hooks ONCE at construction, the only sanctioned
+    # respond_to? use); duck-typed sinks that define all five are
+    # accepted without including the module.
+    #
+    # Unit of observation: a COMPLETION — ONE Client#stream invocation
+    # (one logical request-response on POST {base}/chat/completions with
+    # stream: true). Creation retries are INSIDE the completion (a
+    # retried completion is one completion); tool execution (the Chat
+    # batch) is OUTSIDE it.
+    #
+    # All hook arguments are existing references or immediates — no Hash
+    # payloads, no structs, no interpolated strings, no keyword splats —
+    # so dispatching to a no-op sink allocates nothing on the hot paths.
+    module Telemetry
+      # A sink includes this module and overrides what it wants. The
+      # defaults are no-ops. No base class; no respond_to? dispatch at
+      # notification time.
+      module Sink
+        # Exactly once per completion, before the first POST of the
+        # first attempt. `model_id` is the Model#id String ref
+        # (equal?-stable, never a copy); `request_bytes` is the Integer
+        # bytesize of the serialized request body actually POSTed.
+        def on_completion_start(model_id, request_bytes); end
+
+        # At most once, at the FIRST item the SSE parser yields for the
+        # SUCCESSFUL (2xx) attempt — measured from that attempt's POST
+        # initiation (a retried attempt's clock restarts). Seconds since
+        # the POST, a Float. Does not fire when the completion fails
+        # before any item.
+        def on_completion_ttfb(seconds); end
+
+        # Every Event the consumer block sees, BEFORE the consumer
+        # block, same order — terminals (:done, :error) and the
+        # salvage-path :error included; with a registered sink but no
+        # consumer block, sinks still receive every Event produced at
+        # the yield sites. The argument is the Event ref the accumulator
+        # already allocated.
+        def on_event(event); end
+
+        # Exactly once, when Client#stream returns: after the :done
+        # event's dispatches. `stop_reason` is the mapped Symbol (:stop,
+        # :length, :tool_use); `duration` is the Float from the
+        # completion-start clock; `message` is the accumulator's LIVE
+        # assistant Message (see the read-only convention in
+        # docs/reference/telemetry.md).
+        def on_completion_end(stop_reason, duration, message); end
+
+        # Exactly once on EVERY raise-out of Client#stream — the mapped
+        # paths and any other raise re-raised through the ladder.
+        # `error` is a Symbol derived from the raising class
+        # (demodulized, underscored: :rate_limit_error,
+        # :connection_error, :timeout_error, :cancelled_error,
+        # :stream_error, :runtime_error, …); `duration` is the Float
+        # start-to-raise on the same completion-start clock.
+        def on_completion_error(error, duration); end
+      end
+    end
+  end
+end

data/lib/fast/completions/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   module Completions
-    VERSION = "0.6.0"
+    VERSION = "0.7.0"
   end
 end

data/lib/fast/completions.rb

@@ -13,6 +13,7 @@ require_relative "completions/sse"
 require_relative "completions/codec"
 require_relative "completions/constrained_sampling"
 require_relative "completions/protocol"
+require_relative "completions/telemetry"
 require_relative "completions/client"
 require_relative "completions/tool"
 require_relative "completions/cancellation"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast-completions
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -44,6 +44,7 @@ files:
 - lib/fast/completions/errors.rb
 - lib/fast/completions/protocol.rb
 - lib/fast/completions/sse.rb
+- lib/fast/completions/telemetry.rb
 - lib/fast/completions/tool.rb
 - lib/fast/completions/types.rb
 - lib/fast/completions/version.rb