launchdarkly-server-sdk-ai 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 841cd2b74f8a6e89125e283d2c75442ccb58d64373f04439f882b9d968803818
-  data.tar.gz: 85a82738b8c931e8a9dc466a9cc66ec077e20a2e58fb112e01cd286b1bf551df
+  metadata.gz: e1bdaa1e6cd790510ce57f6e0d63b3719f571ec7b5299cecc430995158240897
+  data.tar.gz: bca165be2cc34d56f742d1d36ed89f199ba9a48c6d9e9f9fea88d1397d5af89f
 SHA512:
-  metadata.gz: 1fb7745e91ce1fb85b965c72f033d3c6ea8978f47d30aa691502251bba83238fbe279d5b67cc3a4e00b8669f3509bf61591bba7fa865f3147db2afc9cb5d3361
-  data.tar.gz: dde93cdaac0a5cf24e6c684d9b1769f9c5e6092e1140bf6f8125e6bc8a2eb0c485cc67f460b195366473f8ca2cda6ba41618d57e2c8e08e73798613c590901fa
+  metadata.gz: 3586d99728f38b474dce7a35d9721a1871610f65eb1336070cce5bad4dbff557181c4956fb25e4b6d5230e18fe0da5c43281164bdb387de4a98d3d4b3d42f09c
+  data.tar.gz: 1f80b447eb3f615380b353ec87b88fb2c997e332a6515adf60bb9322d3d76a625e4a4f061ca536c1a19ecca052d67e90a433df67cd717ad3836d14c5a7dfd8fe

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.4.0](https://github.com/launchdarkly/ruby-server-sdk-ai/compare/0.3.0...0.4.0) (2026-05-15)
+
+
+### ⚠ BREAKING CHANGES
+
+* Replace tracker tuple from completion_config with AIConfig#create_tracker factory
+* Track each AIConfigTracker metric at most once per tracker
+* Add per-execution runId, at-most-once tracking, and cross-process tracker resumption
+
+### Features
+
+* Add Client#create_tracker(token:, context:) to resume a tracker across processes ([20f06f1](https://github.com/launchdarkly/ruby-server-sdk-ai/commit/20f06f1f24a42692953ae44cebea70aaa416b29d))
+* Add per-execution runId to correlate AIConfigTracker events ([20f06f1](https://github.com/launchdarkly/ruby-server-sdk-ai/commit/20f06f1f24a42692953ae44cebea70aaa416b29d))
+* Add per-execution runId, at-most-once tracking, and cross-process tracker resumption ([20f06f1](https://github.com/launchdarkly/ruby-server-sdk-ai/commit/20f06f1f24a42692953ae44cebea70aaa416b29d))
+* Replace tracker tuple from completion_config with AIConfig#create_tracker factory ([20f06f1](https://github.com/launchdarkly/ruby-server-sdk-ai/commit/20f06f1f24a42692953ae44cebea70aaa416b29d))
+* Track each AIConfigTracker metric at most once per tracker ([20f06f1](https://github.com/launchdarkly/ruby-server-sdk-ai/commit/20f06f1f24a42692953ae44cebea70aaa416b29d))
+
 ## [0.3.0](https://github.com/launchdarkly/ruby-server-sdk-ai/compare/0.2.2...0.3.0) (2026-03-05)
 
 

data/PROVENANCE.md

@@ -1,15 +1,15 @@
-## Verifying SDK build provenance with the SLSA framework
+## Verifying SDK build provenance with GitHub artifact attestations
 
-LaunchDarkly uses the [SLSA framework](https://slsa.dev/spec/v1.0/about) (Supply-chain Levels for Software Artifacts) to help developers make their supply chain more secure by ensuring the authenticity and build integrity of our published SDK packages.
+LaunchDarkly uses [GitHub artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds) to help developers make their supply chain more secure by ensuring the authenticity and build integrity of our published SDK packages.
 
-As part of [SLSA requirements for level 3 compliance](https://slsa.dev/spec/v1.0/requirements), LaunchDarkly publishes provenance about our SDK package builds using [GitHub's generic SLSA3 provenance generator](https://github.com/slsa-framework/slsa-github-generator/blob/main/internal/builders/generic/README.md#generation-of-slsa3-provenance-for-arbitrary-projects) for distribution alongside our packages. These attestations are available for download from the GitHub release page for the release version under Assets > `multiple-provenance.intoto.jsonl`.
+LaunchDarkly publishes provenance about our SDK package builds using [GitHub's `actions/attest` action](https://github.com/actions/attest). These attestations are stored in GitHub's attestation API and can be verified using the [GitHub CLI](https://cli.github.com/).
 
-To verify SLSA provenance attestations, we recommend using [slsa-verifier](https://github.com/slsa-framework/slsa-verifier). Example usage for verifying SDK packages is included below:
+To verify build provenance attestations, we recommend using the [GitHub CLI `attestation verify` command](https://cli.github.com/manual/gh_attestation_verify). Example usage for verifying SDK packages is included below:
 
 <!-- x-release-please-start-version -->
 ```
-# Set the version of the SDK to verify
-VERSION=0.3.0
+# Set the version of the library to verify
+VERSION=0.4.0
 ```
 <!-- x-release-please-end -->
 
@@ -17,27 +17,33 @@ VERSION=0.3.0
 # Download gem
 $ gem fetch launchdarkly-server-sdk-ai -v $VERSION
 
-# Download provenance from Github release
-$ curl --location -O \
-  https://github.com/launchdarkly/ruby-server-sdk-ai/releases/download/${VERSION}/launchdarkly-server-sdk-ai-${VERSION}.gem.intoto.jsonl
-
-# Run slsa-verifier to verify provenance against package artifacts 
-$ slsa-verifier verify-artifact \
---provenance-path launchdarkly-server-sdk-ai-${VERSION}.gem.intoto.jsonl \
---source-uri github.com/launchdarkly/ruby-server-sdk-ai \
-launchdarkly-server-sdk-ai-${VERSION}.gem
+# Verify provenance using the GitHub CLI
+$ gh attestation verify launchdarkly-server-sdk-ai-${VERSION}.gem --owner launchdarkly
 ```
 
 Below is a sample of expected output.
-TODO: Verify these are accurate
+
 ```
-Verified signature against tlog entry index 83653185 at URL: https://rekor.sigstore.dev/api/v1/log/entries/24296fb24b8ad77a7df0bbf87a7d5fcaafa551a2101d9f993d251a56a918bb113e81d2c575dc7e25
-Verified build using builder "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.10.0" at commit 14c48a68c45871c27409591969e7f4c0ebdcdf62
-Verifying artifact launchdarkly-server-sdk-ai-1.0.0.gem: PASSED
+Loaded digest sha256:... for file://launchdarkly-server-sdk-ai-0.3.0.gem
+Loaded 1 attestation from GitHub API
+
+The following policy criteria will be enforced:
+- Predicate type must match:................ https://slsa.dev/provenance/v1
+- Source Repository Owner URI must match:... https://github.com/launchdarkly
+- Subject Alternative Name must match regex: (?i)^https://github.com/launchdarkly/
+- OIDC Issuer must match:................... https://token.actions.githubusercontent.com
+
+✓ Verification succeeded!
+
+The following 1 attestation matched the policy criteria
 
-PASSED: Verified SLSA provenance
+- Attestation #1
+  - Build repo:..... launchdarkly/ruby-server-sdk-ai
+  - Build workflow:. .github/workflows/release-please.yml
+  - Signer repo:.... launchdarkly/ruby-server-sdk-ai
+  - Signer workflow: .github/workflows/release-please.yml
 ```
 
-Alternatively, to verify the provenance manually, the SLSA framework specifies [recommendations for verifying build artifacts](https://slsa.dev/spec/v1.0/verifying-artifacts) in their documentation.
+For more information, see [GitHub's documentation on verifying artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds#verifying-artifact-attestations-with-the-github-cli).
 
-**Note:** These instructions do not apply when building our libraries from source. 
+**Note:** These instructions do not apply when building our libraries from source.  

data/lib/server/ai/ai_config_tracker.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'base64'
+require 'json'
 require 'ldclient-rb'
 
 module LaunchDarkly
@@ -39,7 +41,14 @@ module LaunchDarkly
       end
 
       #
-      # The AIConfigTracker class is used to track AI configuration usage.
+      # The AIConfigTracker records metrics for a single AI run. Unless
+      # otherwise noted, the tracker's methods are not safe for concurrent use.
+      #
+      # All events a tracker emits share a runId (a UUIDv4) so LaunchDarkly can
+      # correlate them in metrics views. See individual track methods for their
+      # specific semantics. Call create_tracker on the AI Config to start a new
+      # run. A resumption token preserves the runId, so events emitted by a
+      # tracker reconstructed in another process share the original runId.
       #
       class AIConfigTracker
         attr_reader :ld_client, :config_key, :context, :variation_key, :version, :summary, :model_name, :provider_name
@@ -55,7 +64,7 @@ module LaunchDarkly
         # @param provider_name [String] The name of the AI provider
         # @param context [LDContext] The context used for the flag evaluation
         #
-        def initialize(ld_client:, variation_key:, config_key:, version:, model_name:, provider_name:, context:)
+        def initialize(ld_client:, run_id:, config_key:, variation_key:, version:, context:, model_name:, provider_name:)
           @ld_client = ld_client
           @variation_key = variation_key
           @config_key = config_key
@@ -64,14 +73,62 @@ module LaunchDarkly
           @provider_name = provider_name
           @context = context
           @summary = MetricSummary.new
+          @run_id = run_id
+          @logger = LaunchDarkly::Server::AI.default_logger
+        end
+
+        #
+        # Returns a URL-safe Base64-encoded JSON token that can be used to reconstruct
+        # a tracker in a different process (e.g. for deferred feedback).
+        #
+        # The token contains: runId, configKey, variationKey, version.
+        # modelName and providerName are NOT included.
+        #
+        # @return [String] the resumption token
+        #
+        def resumption_token
+          payload = { runId: @run_id, configKey: @config_key }
+          payload[:variationKey] = @variation_key if @variation_key && !@variation_key.empty?
+          payload[:version] = @version
+          Base64.urlsafe_encode64(JSON.generate(payload), padding: false)
+        end
+
+        #
+        # Reconstructs a tracker from a resumption token.
+        #
+        # @param token [String] A URL-safe Base64-encoded JSON resumption token
+        # @param ld_client [LDClient] The LaunchDarkly client instance
+        # @param context [LDContext] The context for track events
+        # @return [AIConfigTracker] A new tracker instance
+        #
+        def self.from_resumption_token(token:, ld_client:, context:)
+          json = Base64.urlsafe_decode64(token)
+          payload = JSON.parse(json)
+
+          new(
+            ld_client: ld_client,
+            run_id: payload['runId'],
+            config_key: payload['configKey'],
+            variation_key: payload.fetch('variationKey', ''),
+            version: payload['version'],
+            context: context,
+            model_name: '',
+            provider_name: ''
+          )
         end
 
         #
-        # Track the duration of an AI operation
+        # Track the duration of an AI run.
+        #
+        # Records at most once per Tracker; further calls are ignored.
         #
         # @param duration [Integer] The duration in milliseconds
         #
         def track_duration(duration)
+          unless @summary.duration.nil?
+            @logger&.warn("Skipping track_duration: duration already recorded on this tracker. Call create_tracker on the AI Config for a new run. #{flag_data}")
+            return
+          end
           @summary.duration = duration
           @ld_client.track(
             '$ld:ai:duration:total',
@@ -96,11 +153,18 @@ module LaunchDarkly
         end
 
         #
-        # Track time to first token
+        # Track time to first token.
+        #
+        # Records at most once per Tracker; further calls are ignored.
         #
         # @param duration [Integer] The duration in milliseconds
         #
         def track_time_to_first_token(time_to_first_token)
+          unless @summary.time_to_first_token.nil?
+            @logger&.warn("Skipping track_time_to_first_token: time-to-first-token already recorded on this tracker. " \
+                          "Call create_tracker on the AI Config for a new run. #{flag_data}")
+            return
+          end
           @summary.time_to_first_token = time_to_first_token
           @ld_client.track(
             '$ld:ai:tokens:ttf',
@@ -111,11 +175,17 @@ module LaunchDarkly
         end
 
         #
-        # Track user feedback
+        # Track user feedback.
+        #
+        # Records at most once per Tracker; further calls are ignored.
         #
         # @param kind [Symbol] The kind of feedback (:positive or :negative)
         #
         def track_feedback(kind:)
+          unless @summary.feedback.nil?
+            @logger&.warn("Skipping track_feedback: feedback already recorded on this tracker. Call create_tracker on the AI Config for a new run. #{flag_data}")
+            return
+          end
           @summary.feedback = kind
           event_name = kind == :positive ? '$ld:ai:feedback:user:positive' : '$ld:ai:feedback:user:negative'
           @ld_client.track(
@@ -127,9 +197,17 @@ module LaunchDarkly
         end
 
         #
-        # Track a successful AI generation
+        # Track a successful AI generation.
+        #
+        # Records at most once per Tracker. track_success and track_error share
+        # state; only one of the two can record per Tracker, and subsequent
+        # calls are ignored.
         #
         def track_success
+          unless @summary.success.nil?
+            @logger&.warn("Skipping track_success: success/error already recorded on this tracker. Call create_tracker on the AI Config for a new run. #{flag_data}")
+            return
+          end
           @summary.success = true
           @ld_client.track(
             '$ld:ai:generation:success',
@@ -140,9 +218,17 @@ module LaunchDarkly
         end
 
         #
-        # Track an error in AI generation
+        # Track an error in AI generation.
+        #
+        # Records at most once per Tracker. track_success and track_error share
+        # state; only one of the two can record per Tracker, and subsequent
+        # calls are ignored.
         #
         def track_error
+          unless @summary.success.nil?
+            @logger&.warn("Skipping track_error: success/error already recorded on this tracker. Call create_tracker on the AI Config for a new run. #{flag_data}")
+            return
+          end
           @summary.success = false
           @ld_client.track(
             '$ld:ai:generation:error',
@@ -153,11 +239,17 @@ module LaunchDarkly
         end
 
         #
-        # Track token usage
+        # Track token usage.
+        #
+        # Records at most once per Tracker; further calls are ignored.
         #
         # @param token_usage [TokenUsage] An object containing token usage details
         #
         def track_tokens(token_usage)
+          unless @summary.usage.nil?
+            @logger&.warn("Skipping track_tokens: token usage already recorded on this tracker. Call create_tracker on the AI Config for a new run. #{flag_data}")
+            return
+          end
           @summary.usage = token_usage
           if token_usage.total.positive?
             @ld_client.track(
@@ -191,6 +283,10 @@ module LaunchDarkly
         # If the provided block raises, this method will also raise.
         # A failed operation will not have any token usage data.
         #
+        # Subsequent calls re-run the inner block but emit only metrics not
+        # already recorded on this Tracker. Call create_tracker on the AI
+        # Config to start a new run.
+        #
         # @yield The block to track.
         # @return The result of the tracked block.
         #
@@ -208,6 +304,10 @@ module LaunchDarkly
         # Track AWS Bedrock conversation operations.
         # This method tracks the duration, token usage, and success/error status.
         #
+        # Subsequent calls re-run the inner block but emit only metrics not
+        # already recorded on this Tracker. Call create_tracker on the AI
+        # Config to start a new run.
+        #
         # @yield The block to track.
         # @return [Hash] The original response hash.
         #
@@ -222,13 +322,15 @@ module LaunchDarkly
         end
 
         private def flag_data
-          {
-            variationKey: @variation_key,
+          data = {
+            runId: @run_id,
             configKey: @config_key,
             version: @version,
             modelName: @model_name,
             providerName: @provider_name,
           }
+          data[:variationKey] = @variation_key if @variation_key && !@variation_key.empty?
+          data
         end
 
         private def openai_to_token_usage(usage)

data/lib/server/ai/client.rb

@@ -2,6 +2,7 @@
 
 require 'ldclient-rb'
 require 'mustache'
+require 'securerandom'
 require_relative 'ai_config_tracker'
 require_relative 'sdk_info'
 
@@ -100,26 +101,65 @@ module LaunchDarkly
       end
 
       #
-      # The AIConfig class represents an AI configuration.
+      # The AIConfigDefault class represents a user-provided fallback AI
+      # configuration.
       #
-      class AIConfig
-        attr_reader :enabled, :messages, :tracker, :model, :provider
+      # Pass an instance of this class as the +default:+ parameter to
+      # {Client#completion_config} to control the fallback values when a flag
+      # is not found or cannot be evaluated.
+      #
+      # This is an input-only type: it is what an application supplies to the
+      # SDK, never what the SDK returns. The SDK always returns an
+      # {AIConfig}, which carries a tracker factory; AIConfigDefault does not.
+      #
+      class AIConfigDefault
+        attr_reader :enabled, :messages, :model, :provider
 
-        def initialize(enabled: nil, model: nil, messages: nil, tracker: nil, provider: nil)
+        #
+        # Returns a new AIConfigDefault with enabled: false and no model,
+        # messages, or provider.
+        #
+        # @return [AIConfigDefault] a new disabled fallback config
+        #
+        def self.disabled
+          new(enabled: false)
+        end
+
+        def initialize(enabled: false, model: nil, messages: nil, provider: nil)
           @enabled = enabled
           @messages = messages
-          @tracker = tracker
           @model = model
           @provider = provider
         end
 
-        #
-        # Returns a new disabled AIConfig instance.
-        #
-        # @return [AIConfig] a new disabled config
-        #
-        def self.disabled
-          new(enabled: false)
+        def to_h
+          {
+            _ldMeta: {
+              enabled: @enabled || false,
+            },
+            messages: @messages.is_a?(Array) ? @messages.map { |msg| msg&.to_h } : nil,
+            model: @model&.to_h,
+            provider: @provider&.to_h,
+          }
+        end
+      end
+
+      #
+      # The AIConfig class represents an AI configuration returned by the SDK.
+      #
+      # Instances are created by {Client#completion_config} and always carry a
+      # tracker factory; see {#create_tracker}. Do not instantiate directly.
+      # For application-supplied fallback values, use {AIConfigDefault}.
+      #
+      class AIConfig
+        attr_reader :enabled, :messages, :model, :provider
+
+        def initialize(tracker_factory:, enabled: nil, model: nil, messages: nil, provider: nil)
+          @enabled = enabled
+          @messages = messages
+          @model = model
+          @provider = provider
+          @tracker_factory = tracker_factory
         end
 
         def to_h
@@ -132,6 +172,18 @@ module LaunchDarkly
             provider: @provider&.to_h,
           }
         end
+
+        #
+        # Creates a new tracker for a fresh AI run. Each call mints a new
+        # runId (a UUIDv4) that LaunchDarkly uses to correlate the tracker's
+        # events in metrics views. Call this once per AI run; metrics from
+        # different runIds cannot be combined.
+        #
+        # @return [AIConfigTracker] a new tracker instance
+        #
+        def create_tracker
+          @tracker_factory.call
+        end
       end
 
       #
@@ -172,14 +224,26 @@ module LaunchDarkly
         #
         # @param key [String] The key of the configuration flag
         # @param context [LDContext] The context used when evaluating the flag
-        # @param default [AIConfig] The default value to use if the flag is not found
+        # @param default [AIConfigDefault] The default value to use if the flag is not found
         # @param variables [Hash] Optional variables for rendering messages
         # @return [AIConfig] An AIConfig instance containing the configuration data
         #
         def completion_config(key:, context:, default: nil, variables: nil)
           @ld_client.track(TRACK_USAGE_COMPLETION_CONFIG, context, key, 1)
 
-          _completion_config(key:, context:, default: default || AIConfig.disabled, variables:)
+          _completion_config(key:, context:, default: default || AIConfigDefault.disabled, variables:)
+        end
+
+        #
+        # Reconstructs a tracker from a resumption token, allowing deferred tracking
+        # (e.g. feedback from a different process).
+        #
+        # @param token [String] A resumption token obtained from AIConfigTracker#resumption_token
+        # @param context [LDContext] The context for track events
+        # @return [AIConfigTracker] A new tracker instance
+        #
+        def create_tracker(token:, context:)
+          AIConfigTracker.from_resumption_token(token: token, ld_client: @ld_client, context: context)
         end
 
         # @deprecated Use {#completion_config} instead.
@@ -226,20 +290,28 @@ module LaunchDarkly
             )
           end
 
-          tracker = LaunchDarkly::Server::AI::AIConfigTracker.new(
-            ld_client: @ld_client,
-            variation_key: variation.dig(:_ldMeta, :variationKey) || '',
-            config_key: key,
-            version: variation.dig(:_ldMeta, :version) || 1,
-            model_name: model&.name || '',
-            provider_name: provider_config&.name || '',
-            context:
-          )
+          variation_key = variation.dig(:_ldMeta, :variationKey) || ''
+          version = variation.dig(:_ldMeta, :version) || 1
+          model_name = model&.name || ''
+          provider_name = provider_config&.name || ''
+
+          tracker_factory = lambda {
+            LaunchDarkly::Server::AI::AIConfigTracker.new(
+              ld_client: @ld_client,
+              run_id: SecureRandom.uuid,
+              variation_key: variation_key,
+              config_key: key,
+              version: version,
+              model_name: model_name,
+              provider_name: provider_name,
+              context: context
+            )
+          }
 
           AIConfig.new(
             enabled: variation.dig(:_ldMeta, :enabled) || false,
             messages:,
-            tracker:,
+            tracker_factory:,
             model:,
             provider: provider_config
           )

data/lib/server/ai/version.rb

@@ -3,7 +3,7 @@
 module LaunchDarkly
   module Server
     module AI
-      VERSION = '0.3.0' # x-release-please-version
+      VERSION = '0.4.0' # x-release-please-version
     end
   end
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: launchdarkly-server-sdk-ai
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - LaunchDarkly
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-05 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: launchdarkly-server-sdk
   requirement: !ruby/object:Gem::Requirement