refactor: Move UUID generation from tracker constructor to factory closure

The run_id parameter on LDAIConfigTracker is now required (no default).
UUID generation happens in the tracker_factory closure in client.py,
keeping the tracker itself a plain data holder.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jsonbailey

packages/sdk/server-ai/src/ldai/client.py

@@ -1,5 +1,6 @@
 import base64
 import json
+import uuid
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 import chevron
@@ -863,6 +864,7 @@ def tracker_factory() -> LDAIConfigTracker:
                 model_name,
                 provider_name,
                 context,
+                run_id=str(uuid.uuid4()),
                 graph_key=graph_key,
             )
 

packages/sdk/server-ai/src/ldai/tracker.py

@@ -2,7 +2,6 @@
 import json
 import logging
 import time
-import uuid
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Callable, Dict, Iterable, List, Optional
@@ -83,8 +82,8 @@ def __init__(
         model_name: str,
         provider_name: str,
         context: Context,
+        run_id: str,
         graph_key: Optional[str] = None,
-        run_id: Optional[str] = None,
     ):
         """
         Initialize an AI Config tracker.
@@ -96,9 +95,9 @@ def __init__(
         :param model_name: Name of the model used.
         :param provider_name: Name of the provider used.
         :param context: Context for evaluation.
+        :param run_id: Unique identifier for this execution.
         :param graph_key: When set, include ``graphKey`` in all event payloads
             (e.g. config-level metrics inside a graph).
-        :param run_id: Optional run ID. When not provided, a new UUID is generated.
         """
         self._ld_client = ld_client
         self._variation_key = variation_key
@@ -109,7 +108,7 @@ def __init__(
         self._context = context
         self._graph_key = graph_key
         self._summary = LDAIMetricSummary()
-        self._run_id = run_id or str(uuid.uuid4())
+        self._run_id = run_id
         self._tracked: Dict[str, bool] = {}
 
     @property

packages/sdk/server-ai/tests/test_judge.py

@@ -54,7 +54,8 @@ def context() -> Context:
 @pytest.fixture
 def tracker(client: LDClient, context: Context) -> LDAIConfigTracker:
     return LDAIConfigTracker(
-        client, 'judge-v1', 'judge-config', 1, 'gpt-4', 'openai', context
+        client, 'judge-v1', 'judge-config', 1, 'gpt-4', 'openai', context,
+        run_id='test-run-id',
     )
 
 

packages/sdk/server-ai/tests/test_tracker.py

@@ -43,7 +43,7 @@ def client(td: TestData) -> LDClient:
 
 def test_summary_starts_empty(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 1, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 1, "fakeModel", "fakeProvider", context, run_id="test-run-id")
 
     assert tracker.get_summary().duration is None
     assert tracker.get_summary().feedback is None
@@ -53,7 +53,7 @@ def test_summary_starts_empty(client: LDClient):
 
 def test_tracks_duration(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_duration(100)
 
     client.track.assert_called_with(  # type: ignore
@@ -68,7 +68,7 @@ def test_tracks_duration(client: LDClient):
 
 def test_tracks_duration_of(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_duration_of(lambda: sleep(0.01))
 
     calls = client.track.mock_calls  # type: ignore
@@ -87,7 +87,7 @@ def test_tracks_duration_of(client: LDClient):
 
 def test_tracks_time_to_first_token(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_time_to_first_token(100)
 
     client.track.assert_called_with(  # type: ignore
@@ -102,7 +102,7 @@ def test_tracks_time_to_first_token(client: LDClient):
 
 def test_tracks_duration_of_with_exception(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
 
     def sleep_and_throw():
         sleep(0.01)
@@ -130,7 +130,7 @@ def sleep_and_throw():
 
 def test_tracks_token_usage(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
 
     tokens = TokenUsage(300, 200, 100)
     tracker.track_tokens(tokens)
@@ -163,7 +163,7 @@ def test_tracks_token_usage(client: LDClient):
 
 def test_tracks_bedrock_metrics(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
 
     bedrock_result = {
         "ResponseMetadata": {"HTTPStatusCode": 200},
@@ -220,7 +220,7 @@ def test_tracks_bedrock_metrics(client: LDClient):
 
 def test_tracks_bedrock_metrics_with_error(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
 
     bedrock_result = {
         "ResponseMetadata": {"HTTPStatusCode": 500},
@@ -277,7 +277,7 @@ def test_tracks_bedrock_metrics_with_error(client: LDClient):
 
 def test_tracks_openai_metrics(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
 
     class Result:
         def __init__(self):
@@ -330,7 +330,7 @@ def get_result():
 
 def test_tracks_openai_metrics_with_exception(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
 
     def raise_exception():
         raise ValueError("Something went wrong")
@@ -364,7 +364,7 @@ def raise_exception():
 )
 def test_tracks_feedback(client: LDClient, kind: FeedbackKind, label: str):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
 
     tracker.track_feedback({"kind": kind})
 
@@ -379,7 +379,7 @@ def test_tracks_feedback(client: LDClient, kind: FeedbackKind, label: str):
 
 def test_tracks_success(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_success()
 
     calls = [
@@ -398,7 +398,7 @@ def test_tracks_success(client: LDClient):
 
 def test_tracks_error(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_error()
 
     calls = [
@@ -417,7 +417,7 @@ def test_tracks_error(client: LDClient):
 
 def test_error_after_success_is_blocked(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_success()
     tracker.track_error()
 
@@ -446,7 +446,7 @@ def _base_td() -> dict:
 def test_config_tracker_includes_graph_key_when_provided(client: LDClient):
     context = Context.create("user-key")
     tracker = LDAIConfigTracker(
-        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, graph_key="my-graph"
+        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id", graph_key="my-graph"
     )
     expected = {**_base_td(), "graphKey": "my-graph"}
     tracker.track_success()
@@ -456,7 +456,7 @@ def test_config_tracker_includes_graph_key_when_provided(client: LDClient):
 def test_config_tracker_track_tokens_with_graph_key(client: LDClient):
     context = Context.create("user-key")
     tracker = LDAIConfigTracker(
-        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, graph_key="g1"
+        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id", graph_key="g1"
     )
     tokens = TokenUsage(10, 4, 6)
     expected = {**_base_td(), "graphKey": "g1"}
@@ -467,7 +467,7 @@ def test_config_tracker_track_tokens_with_graph_key(client: LDClient):
 def test_config_tracker_track_feedback_with_graph_key(client: LDClient):
     context = Context.create("user-key")
     tracker = LDAIConfigTracker(
-        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, graph_key="gx"
+        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id", graph_key="gx"
     )
     expected = {**_base_td(), "graphKey": "gx"}
     tracker.track_feedback({"kind": FeedbackKind.Positive})
@@ -479,7 +479,7 @@ def test_config_tracker_track_feedback_with_graph_key(client: LDClient):
 def test_config_tracker_track_tool_call(client: LDClient):
     context = Context.create("user-key")
     tracker = LDAIConfigTracker(
-        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context
+        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id"
     )
     expected = {**_base_td(), "toolKey": "search"}
     tracker.track_tool_call("search")
@@ -489,7 +489,7 @@ def test_config_tracker_track_tool_call(client: LDClient):
 def test_config_tracker_track_tool_call_with_graph_key(client: LDClient):
     context = Context.create("user-key")
     tracker = LDAIConfigTracker(
-        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, graph_key="my-graph"
+        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id", graph_key="my-graph"
     )
     expected = {**_base_td(), "graphKey": "my-graph", "toolKey": "calc"}
     tracker.track_tool_call("calc")
@@ -499,7 +499,7 @@ def test_config_tracker_track_tool_call_with_graph_key(client: LDClient):
 def test_config_tracker_track_tool_calls(client: LDClient):
     context = Context.create("user-key")
     tracker = LDAIConfigTracker(
-        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, graph_key="g"
+        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id", graph_key="g"
     )
     tracker.track_tool_calls(["a", "b"])
     assert client.track.call_count == 2  # type: ignore
@@ -520,7 +520,7 @@ def test_config_tracker_track_tool_calls(client: LDClient):
 def test_config_tracker_track_metrics_of(client: LDClient):
     context = Context.create("user-key")
     tracker = LDAIConfigTracker(
-        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context
+        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id"
     )
 
     def fn():
@@ -540,7 +540,7 @@ def extract(r):
 async def test_config_tracker_track_metrics_of_async_passes_graph_key(client: LDClient):
     context = Context.create("user-key")
     tracker = LDAIConfigTracker(
-        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, graph_key="gg"
+        client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id", graph_key="gg"
     )
 
     async def fn():
@@ -588,7 +588,7 @@ def test_ai_graph_tracker_track_total_tokens_tracks_when_positive(client: LDClie
 
 def test_duplicate_track_duration_is_ignored(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_duration(100)
     tracker.track_duration(200)
 
@@ -598,7 +598,7 @@ def test_duplicate_track_duration_is_ignored(client: LDClient):
 
 def test_duplicate_track_time_to_first_token_is_ignored(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_time_to_first_token(50)
     tracker.track_time_to_first_token(75)
 
@@ -608,7 +608,7 @@ def test_duplicate_track_time_to_first_token_is_ignored(client: LDClient):
 
 def test_duplicate_track_tokens_is_ignored(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tokens1 = TokenUsage(300, 200, 100)
     tokens2 = TokenUsage(600, 400, 200)
     tracker.track_tokens(tokens1)
@@ -621,7 +621,7 @@ def test_duplicate_track_tokens_is_ignored(client: LDClient):
 
 def test_duplicate_track_success_is_ignored(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_success()
     tracker.track_success()
 
@@ -631,7 +631,7 @@ def test_duplicate_track_success_is_ignored(client: LDClient):
 
 def test_duplicate_track_error_is_ignored(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_error()
     tracker.track_error()
 
@@ -641,7 +641,7 @@ def test_duplicate_track_error_is_ignored(client: LDClient):
 
 def test_duplicate_track_feedback_is_ignored(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_feedback({"kind": FeedbackKind.Positive})
     tracker.track_feedback({"kind": FeedbackKind.Negative})
 
@@ -651,18 +651,16 @@ def test_duplicate_track_feedback_is_ignored(client: LDClient):
 
 def test_track_data_includes_run_id(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="my-run-id")
     tracker.track_success()
 
     track_data = client.track.call_args[0][2]  # type: ignore
-    assert "runId" in track_data
-    assert isinstance(track_data["runId"], str)
-    assert len(track_data["runId"]) == 36  # UUID format
+    assert track_data["runId"] == "my-run-id"
 
 
 def test_run_id_is_consistent_across_track_calls(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context)
+    tracker = LDAIConfigTracker(client, "variation-key", "config-key", 3, "fakeModel", "fakeProvider", context, run_id="test-run-id")
     tracker.track_success()
     tracker.track_duration(100)
 
@@ -680,7 +678,7 @@ def test_resumption_token_round_trip(client: LDClient):
     import json
 
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "var-key", "cfg-key", 5, "gpt-4", "openai", context)
+    tracker = LDAIConfigTracker(client, "var-key", "cfg-key", 5, "gpt-4", "openai", context, run_id="test-run-id")
 
     token = tracker.resumption_token
     # Token has no padding — add it back before decoding
@@ -698,7 +696,7 @@ def test_resumption_token_round_trip(client: LDClient):
 
 def test_resumption_token_has_no_padding(client: LDClient):
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "var-key", "cfg-key", 1, "model", "provider", context)
+    tracker = LDAIConfigTracker(client, "var-key", "cfg-key", 1, "model", "provider", context, run_id="test-run-id")
 
     token = tracker.resumption_token
     assert "=" not in token
@@ -708,7 +706,7 @@ def test_resumption_token_is_url_safe_base64(client: LDClient):
     import base64
 
     context = Context.create("user-key")
-    tracker = LDAIConfigTracker(client, "var-key", "cfg-key", 1, "model", "provider", context)
+    tracker = LDAIConfigTracker(client, "var-key", "cfg-key", 1, "model", "provider", context, run_id="test-run-id")
 
     token = tracker.resumption_token
     # Should decode without error using urlsafe variant (with padding restored)
@@ -740,6 +738,7 @@ def test_client_create_tracker_from_resumption_token():
     # Create an original tracker and get its token
     original = LDAIConfigTracker(
         mock_client, "var-abc", "my-config", 7, "gpt-4", "openai", Context.create("original-user"),
+        run_id="original-run-id-123",
     )
     token = original.resumption_token