feat!: Add per-execution runId, at-most-once tracking, and cross-process tracker resumption (#249)

Author: jsonbailey

pkgs/sdk/server-ai/src/Config/ConfigFactory.cs

@@ -86,7 +86,7 @@ private LdAiCompletionConfig BuildCompletionFromDefault(
             key,
             defaultValue.Enabled ?? true,
             variationKey: "",
-            version: 0,
+            version: 1,
             messages,
             defaultValue.Model,
             defaultValue.Provider,
@@ -124,18 +124,26 @@ private IReadOnlyList<Message> InterpolateMessages(
 
     private Func<LdAiConfigBase, ILdAiConfigTracker> TrackerFactoryFor(Context context)
     {
-        return cfg => new LdAiConfigTracker(_client, cfg, context);
+        return cfg => new LdAiConfigTracker(
+            _client,
+            Guid.NewGuid().ToString(),
+            cfg.Key,
+            cfg.VariationKey,
+            cfg.Version,
+            context,
+            cfg.Model?.Name,
+            cfg.Provider?.Name);
     }
 
     private static (bool Enabled, string VariationKey, int Version, string Mode) ParseMeta(LdValue value)
     {
         var meta = value.Get("_ldMeta");
         var enabled = meta.Get("enabled").AsBool;
         var variationKey = meta.Get("variationKey").AsString ?? "";
-        var version = meta.Get("version").AsInt;
+        var versionValue = meta.Get("version");
+        var version = versionValue.IsNull ? 1 : versionValue.AsInt;
         // Default to the completion mode when _ldMeta.mode is missing or non-string: legacy
-        // flags predate the mode tag, so treating them as completion configs matches the
-        // existing shape on the wire.
+        // flags predate the mode tag and were always served as completion configs.
         var mode = meta.Get("mode").AsString ?? LdAiCompletionConfig.Mode;
         return (enabled, variationKey, version, mode);
     }

pkgs/sdk/server-ai/src/Config/ModelConfig.cs

@@ -1,4 +1,5 @@
 using System.Collections.Generic;
+using System.Collections.Immutable;
 
 namespace LaunchDarkly.Sdk.Server.Ai.Config;
 
@@ -25,7 +26,11 @@ public sealed record ModelConfig
     internal ModelConfig(string name, IReadOnlyDictionary<string, LdValue> parameters, IReadOnlyDictionary<string, LdValue> custom)
     {
         Name = name;
-        Parameters = parameters;
-        Custom = custom;
+        // Materialize into an ImmutableDictionary so a consumer that downcasts to
+        // IDictionary<> can't mutate the stored map. The cast still succeeds (the
+        // contract is still IReadOnlyDictionary<>) but write members throw
+        // NotSupportedException at runtime, matching the typed read-only promise.
+        Parameters = parameters?.ToImmutableDictionary() ?? ImmutableDictionary<string, LdValue>.Empty;
+        Custom = custom?.ToImmutableDictionary() ?? ImmutableDictionary<string, LdValue>.Empty;
     }
 }

pkgs/sdk/server-ai/src/Interfaces/ILdAiClient.cs

@@ -41,4 +41,17 @@ public LdAiCompletionConfig CompletionConfig(string key, Context context, LdAiCo
     [Obsolete("Use CompletionConfig instead.")]
     public LdAiCompletionConfig Config(string key, Context context, LdAiCompletionConfigDefault defaultValue = null,
         IReadOnlyDictionary<string, object> variables = null);
+
+    /// <summary>
+    /// Reconstructs a tracker from a resumption token. This enables cross-process scenarios
+    /// such as deferred feedback, where a tracker's runId needs to be reused in a different
+    /// process or at a later time.
+    ///
+    /// The reconstructed tracker will have empty model and provider names, as these are not
+    /// included in the resumption token.
+    /// </summary>
+    /// <param name="resumptionToken">the resumption token obtained from <see cref="ILdAiConfigTracker.ResumptionToken"/></param>
+    /// <param name="context">the context to use for track events</param>
+    /// <returns>a tracker associated with the original runId</returns>
+    public ILdAiConfigTracker CreateTracker(string resumptionToken, Context context);
 }

pkgs/sdk/server-ai/src/Interfaces/ILdAiConfigTracker.cs

@@ -5,16 +5,36 @@
 namespace LaunchDarkly.Sdk.Server.Ai.Interfaces;
 
 /// <summary>
-/// A utility capable of generating events related to a specific AI model
-/// configuration.
+/// Records metrics for a single AI run.
 /// </summary>
+/// <remarks>
+/// All events emitted by a tracker share a runId (a UUIDv4) so LaunchDarkly can correlate
+/// them. See individual track methods for their specific semantics.
+/// Call <c>CreateTracker</c> on the AI Config to start a new run. A
+/// <see cref="ResumptionToken"/> preserves the runId, so events emitted by a tracker
+/// reconstructed in another process correlate with the original tracker's runId.
+/// </remarks>
 public interface ILdAiConfigTracker
 {
+    /// <summary>
+    /// A URL-safe Base64-encoded token that can be used to reconstruct this tracker in a different
+    /// process or at a later time. The token contains the runId, configKey, variationKey, and version.
+    ///
+    /// Use <c>LdAiConfigTracker.FromResumptionToken</c> to reconstruct a tracker from this token.
+    /// </summary>
+    public string ResumptionToken { get; }
+
+    /// <summary>
+    /// A summary of the metrics tracked by this tracker.
+    /// </summary>
+    public MetricSummary Summary { get; }
+
     /// <summary>
     /// Tracks a duration metric related to this config. For example, if a particular operation
     /// related to usage of the AI model takes 100ms, this can be tracked and made available in
     /// LaunchDarkly.
     /// </summary>
+    /// <remarks>Records at most once per Tracker; further calls are ignored.</remarks>
     /// <param name="durationMs">the duration in milliseconds</param>
     public void TrackDuration(float durationMs);
 
@@ -30,28 +50,38 @@ public interface ILdAiConfigTracker
     /// <typeparam name="T">type of the task's result</typeparam>
     /// <returns>the task</returns>
     public Task<T> TrackDurationOfTask<T>(Task<T> task);
-    
+
     /// <summary>
     /// Tracks the time it takes for the first token to be generated.
     /// </summary>
+    /// <remarks>Records at most once per Tracker; further calls are ignored.</remarks>
     /// <param name="timeToFirstTokenMs">the duration in milliseconds</param>
     public void TrackTimeToFirstToken(float timeToFirstTokenMs);
 
     /// <summary>
     /// Tracks feedback (positive or negative) related to the output of the model.
     /// </summary>
+    /// <remarks>Records at most once per Tracker; further calls are ignored.</remarks>
     /// <param name="feedback">the feedback</param>
     /// <exception cref="ArgumentOutOfRangeException">thrown if the feedback value is not <see cref="Feedback.Positive"/> or <see cref="Feedback.Negative"/></exception>
     public void TrackFeedback(Feedback feedback);
 
     /// <summary>
     /// Tracks a generation event related to this config.
     /// </summary>
+    /// <remarks>
+    /// Records at most once per Tracker. TrackSuccess and TrackError share state; only
+    /// one of the two can record per Tracker, and subsequent calls are ignored.
+    /// </remarks>
     public void TrackSuccess();
 
     /// <summary>
     /// Tracks an unsuccessful generation event related to this config.
     /// </summary>
+    /// <remarks>
+    /// Records at most once per Tracker. TrackSuccess and TrackError share state; only
+    /// one of the two can record per Tracker, and subsequent calls are ignored.
+    /// </remarks>
     public void TrackError();
 
     /// <summary>
@@ -86,13 +116,18 @@ public interface ILdAiConfigTracker
     /// Task is automatically measured and recorded as the latency metric associated with this request.
     ///
     /// </summary>
+    /// <remarks>
+    /// Subsequent calls re-run the task but emit only metrics not already recorded on this Tracker.
+    /// Call <c>CreateTracker</c> on the AI Config to start a new run.
+    /// </remarks>
     /// <param name="request">a task representing the request</param>
     /// <returns>the task</returns>
     public Task<Response> TrackRequest(Task<Response> request);
 
     /// <summary>
     /// Tracks token usage related to this config.
     /// </summary>
+    /// <remarks>Records at most once per Tracker; further calls are ignored.</remarks>
     /// <param name="usage">the token usage</param>
     public void TrackTokens(Usage usage);
 }

pkgs/sdk/server-ai/src/LdAiClient.cs

@@ -72,4 +72,11 @@ public LdAiCompletionConfig Config(string key, Context context, LdAiCompletionCo
     {
         return CompletionConfig(key, context, defaultValue, variables);
     }
+
+
+    /// <inheritdoc/>
+    public ILdAiConfigTracker CreateTracker(string resumptionToken, Context context)
+    {
+        return LdAiConfigTracker.FromResumptionToken(resumptionToken, _client, context);
+    }
 }